# API reference Explore the versioned request and response schemas generated from public routes. ## Use the generated contract The server-to-server base URL is https://api.lineblink.com/v1/external. The generated OpenAPI document defines supported routes, validation rules, response envelopes and required scopes. Reference operations below use the same source as route validation. Do not send a production key from this public page. Copy an example into your trusted server environment and replace its placeholders there. ## Response conventions Dates and timestamps use ISO 8601; mutation timestamps and event occurrence times are UTC. Null means an explicitly absent value. A guest identity field may be omitted when the key lacks its sensitive-data scope. Success envelopes keep resource names such as entry, entries, businesses and queues. List responses provide nextCursor where pagination applies. Errors provide a stable code, safe error message and requestId. ## OpenAPI reference ```json { "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "LineBlink Public API", "version": "1.0.0", "description": "Business and Enterprise waitlist integrations. See the public guides for consent, booking availability, retention, retries, and launch status.", "contact": { "url": "https://lineblink.com/contact" } }, "servers": [ { "url": "https://api.lineblink.com/v1/external", "description": "Production API; access requires enabled launch flags and an eligible tenant." } ], "externalDocs": { "description": "Task guides and quickstart", "url": "https://lineblink.com/docs/api" }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "LineBlink API key" } } }, "paths": { "/me": { "get": { "operationId": "getConnection", "summary": "Test and identify a connection", "description": "Returns only the authenticated connection. Plan eligibility applies.", "security": [ { "bearerAuth": [] } ], "x-required-scope": null, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationType": { "type": "string", "enum": [ "api", "zapier" ] }, "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "waitlist:read", "waitlist:write", "guest:read", "events:read", "webhooks:read", "webhooks:write", "analytics:read" ] } }, "restrictions": { "type": "object", "properties": { "businessIds": { "type": "array", "items": { "type": "string" } }, "queueIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "businessIds", "queueIds" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "publicApiEnabled": { "type": "boolean" }, "zapierEnabled": { "type": "boolean" }, "webhooksEnabled": { "type": "boolean" }, "canManageIntegrations": { "type": "boolean" }, "unavailableReason": { "anyOf": [ { "type": "string", "enum": [ "launch_disabled", "billing_unavailable", "disabled_account", "demo_account", "subscription_required", "upgrade_required", "email_verification_required", "management_forbidden" ] }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "readsPerMinute": { "type": "number" }, "writesPerMinute": { "type": "number" }, "tenantReadsPerMinute": { "type": "number" }, "tenantWritesPerMinute": { "type": "number" }, "activeKeys": { "type": "number" }, "webhookSubscriptions": { "type": "number" }, "defaultKeyExpiryDays": { "type": "number" }, "maximumKeyExpiryDays": { "type": "number" } }, "required": [ "readsPerMinute", "writesPerMinute", "tenantReadsPerMinute", "tenantWritesPerMinute", "activeKeys", "webhookSubscriptions", "defaultKeyExpiryDays", "maximumKeyExpiryDays" ], "additionalProperties": false }, "migrationExpiresAt": { "type": [ "string", "null" ] } }, "required": [ "publicApiEnabled", "zapierEnabled", "webhooksEnabled", "canManageIntegrations", "unavailableReason", "limits" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "readsPerMinute": { "type": "number" }, "writesPerMinute": { "type": "number" }, "tenantReadsPerMinute": { "type": "number" }, "tenantWritesPerMinute": { "type": "number" }, "activeKeys": { "type": "number" }, "webhookSubscriptions": { "type": "number" }, "defaultKeyExpiryDays": { "type": "number" }, "maximumKeyExpiryDays": { "type": "number" } }, "required": [ "readsPerMinute", "writesPerMinute", "tenantReadsPerMinute", "tenantWritesPerMinute", "activeKeys", "webhookSubscriptions", "defaultKeyExpiryDays", "maximumKeyExpiryDays" ], "additionalProperties": false } }, "required": [ "integrationType", "tenant", "scopes", "restrictions", "capabilities", "limits" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/businesses": { "get": { "operationId": "listBusinesses", "summary": "List available businesses", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "businesses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timeZone": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "serviceName": { "type": "string" }, "baseDurationMinutes": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id", "serviceName", "baseDurationMinutes", "isActive" ], "additionalProperties": false } }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "id", "label", "type", "required" ], "additionalProperties": false } } }, "required": [ "id", "name", "slug", "timeZone", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "businesses", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/businesses/{businessId}": { "get": { "operationId": "getBusiness", "summary": "Get a business and join requirements", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "businessId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "business": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timeZone": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "serviceName": { "type": "string" }, "baseDurationMinutes": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id", "serviceName", "baseDurationMinutes", "isActive" ], "additionalProperties": false } }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "id", "label", "type", "required" ], "additionalProperties": false } } }, "required": [ "id", "name", "slug", "timeZone", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "business" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/queues": { "get": { "operationId": "listQueues", "summary": "List business lines", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "businessId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "name": { "type": "string" }, "activeGuests": { "type": "number" }, "averageWaitMinutes": { "type": "number" }, "timeZone": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "serviceName": { "type": "string" }, "baseDurationMinutes": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id", "serviceName", "baseDurationMinutes", "isActive" ], "additionalProperties": false } }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "id", "label", "type", "required" ], "additionalProperties": false } }, "workingHours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "days": { "type": "object", "properties": { "mon": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "tue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "wed": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "thu": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "fri": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sun": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false } }, "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "additionalProperties": false } }, "required": [ "enabled", "start", "end", "days" ], "additionalProperties": false }, "availability": { "type": "object", "properties": { "walkInsEnabled": { "type": "boolean" }, "walkInsPaused": { "type": "boolean" }, "bookingsEnabled": { "type": "boolean" }, "bookingsPaused": { "type": "boolean" }, "bookingWindow": { "type": "string", "const": "same_business_day" }, "bookingSlotMinutes": { "type": "number" }, "bookingHours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "days": { "type": "object", "properties": { "mon": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "tue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "wed": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "thu": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "fri": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sun": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false } }, "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "additionalProperties": false } }, "required": [ "enabled", "start", "end", "days" ], "additionalProperties": false } }, "required": [ "walkInsEnabled", "walkInsPaused", "bookingsEnabled", "bookingsPaused", "bookingWindow", "bookingSlotMinutes", "bookingHours" ], "additionalProperties": false } }, "required": [ "id", "businessId", "name", "activeGuests", "averageWaitMinutes", "timeZone", "services", "customFields", "workingHours", "availability" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "queues", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/queues/{queueId}": { "get": { "operationId": "getQueue", "summary": "Get line services, fields and availability", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "queueId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "name": { "type": "string" }, "activeGuests": { "type": "number" }, "averageWaitMinutes": { "type": "number" }, "timeZone": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "serviceName": { "type": "string" }, "baseDurationMinutes": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id", "serviceName", "baseDurationMinutes", "isActive" ], "additionalProperties": false } }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "id", "label", "type", "required" ], "additionalProperties": false } }, "workingHours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "days": { "type": "object", "properties": { "mon": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "tue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "wed": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "thu": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "fri": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sun": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false } }, "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "additionalProperties": false } }, "required": [ "enabled", "start", "end", "days" ], "additionalProperties": false }, "availability": { "type": "object", "properties": { "walkInsEnabled": { "type": "boolean" }, "walkInsPaused": { "type": "boolean" }, "bookingsEnabled": { "type": "boolean" }, "bookingsPaused": { "type": "boolean" }, "bookingWindow": { "type": "string", "const": "same_business_day" }, "bookingSlotMinutes": { "type": "number" }, "bookingHours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "days": { "type": "object", "properties": { "mon": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "tue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "wed": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "thu": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "fri": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false }, "sun": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "enabled", "start", "end" ], "additionalProperties": false } }, "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "additionalProperties": false } }, "required": [ "enabled", "start", "end", "days" ], "additionalProperties": false } }, "required": [ "walkInsEnabled", "walkInsPaused", "bookingsEnabled", "bookingsPaused", "bookingWindow", "bookingSlotMinutes", "bookingHours" ], "additionalProperties": false } }, "required": [ "id", "businessId", "name", "activeGuests", "averageWaitMinutes", "timeZone", "services", "customFields", "workingHours", "availability" ], "additionalProperties": false } }, "required": [ "queue" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/entries": { "get": { "operationId": "listEntries", "summary": "List entries or find an external reference", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "queueId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "externalReference", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 160 } }, { "name": "updatedAfter", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "queueId": { "type": "string" }, "businessId": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "quotedWaitMinutes": { "type": "number" }, "joinedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "isBooking": { "type": "boolean" }, "scheduledFor": { "type": [ "string", "null" ] }, "customData": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] } }, "fullName": { "type": "string" }, "phoneCountryCode": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] } }, "required": [ "id", "queueId", "businessId", "externalReference", "version", "status", "quotedWaitMinutes", "joinedAt", "updatedAt", "isBooking", "scheduledFor", "customData" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createEntry", "summary": "Create a guest or same-day booking", "description": "Requires waitlist:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string", "minLength": 1, "maxLength": 120 }, "phoneCountryCode": { "type": "string", "maxLength": 8 }, "phoneNumber": { "type": "string", "maxLength": 32 }, "customData": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] } }, "queueId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quotedWaitMinutes": { "type": "integer", "minimum": 0, "maximum": 43200 }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 128 }, "smsConsent": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 100 }, "consentedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "disclosureVersion": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "source", "consentedAt", "disclosureVersion" ], "additionalProperties": false }, "isBooking": { "type": "boolean" }, "scheduledFor": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "fullName", "queueId" ], "additionalProperties": false, "description": "Bookings require isBooking and scheduledFor together and are limited to the current business-local day. Phone fields must be supplied together. SMS requires explicit consent with a timestamp no later than now. Custom data allows at most 12 configured scalar fields." } } } }, "responses": { "201": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "string" }, "guestId": { "type": "string" }, "bookingId": { "type": [ "string", "null" ] } }, "required": [ "id", "guestId", "bookingId" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/entries/{entryId}": { "get": { "operationId": "getEntry", "summary": "Look up an entry or booking", "description": "Requires waitlist:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:read", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "string" }, "queueId": { "type": "string" }, "businessId": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "quotedWaitMinutes": { "type": "number" }, "joinedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "isBooking": { "type": "boolean" }, "scheduledFor": { "type": [ "string", "null" ] }, "customData": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] } }, "fullName": { "type": "string" }, "phoneCountryCode": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] } }, "required": [ "id", "queueId", "businessId", "externalReference", "version", "status", "quotedWaitMinutes", "joinedAt", "updatedAt", "isBooking", "scheduledFor", "customData" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } }, "patch": { "operationId": "updateEntry", "summary": "Update supported guest fields", "description": "Requires waitlist:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:write", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string", "minLength": 1, "maxLength": 120 }, "phoneCountryCode": { "type": "string", "maxLength": 8 }, "phoneNumber": { "type": "string", "maxLength": 32 }, "customData": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] } }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "entryId": { "type": "string" }, "version": { "type": "number" } }, "required": [ "entryId", "version" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/waitlist/entries/{entryId}/status": { "patch": { "operationId": "updateEntryStatus", "summary": "Change an entry status", "description": "Requires waitlist:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:write", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "expectedStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "maxLength": 300 } }, "required": [ "status", "expectedStatus" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "entryId": { "type": "string" }, "fromStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "toStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "entryId", "fromStatus", "toStatus" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/bookings/{entryId}/reschedule": { "post": { "operationId": "rescheduleBooking", "summary": "Reschedule a same-day booking", "description": "Requires waitlist:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:write", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledFor": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "scheduledFor", "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "entryId": { "type": "string" }, "scheduledFor": { "type": "string" }, "version": { "type": "number" } }, "required": [ "entryId", "scheduledFor", "version" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/bookings/{entryId}/cancel": { "post": { "operationId": "cancelBooking", "summary": "Cancel an active booking", "description": "Requires waitlist:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "waitlist:write", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "maxLength": 300 } }, "required": [ "expectedStatus", "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "entryId": { "type": "string" }, "fromStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "toStatus": { "type": "string", "enum": [ "waiting", "ready", "confirmed", "in_service", "completed", "cancelled", "no_show" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "entryId", "fromStatus", "toStatus" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "summary": "Summarize retained entries joined in a UTC date range", "description": "Requires analytics:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "analytics:read", "parameters": [ { "name": "businessId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "queueId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "timeZone": { "type": "string", "const": "UTC" }, "businessId": { "type": [ "string", "null" ] }, "queueId": { "type": [ "string", "null" ] }, "summary": { "type": "object", "properties": { "joins": { "type": "number" }, "completed": { "type": "number" }, "cancelled": { "type": "number" }, "noShows": { "type": "number" }, "active": { "type": "number" }, "avgWaitMinutes": { "type": "number" }, "completionRate": { "type": "number" } }, "required": [ "joins", "completed", "cancelled", "noShows", "active", "avgWaitMinutes", "completionRate" ], "additionalProperties": false } }, "required": [ "from", "to", "timeZone", "businessId", "queueId", "summary" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "Read immutable events from the seven-day recovery window", "description": "Requires events:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "events:read", "parameters": [ { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } }, { "name": "businessId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "queueId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] }, "schemaVersion": { "type": "number", "const": 1 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "tenantId": { "type": "string" }, "businessId": { "type": [ "string", "null" ] }, "queueId": { "type": "string" }, "resourceId": { "type": "string" }, "resourceVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": { "type": "object", "properties": { "entryId": { "type": "string" }, "status": { "type": "string" }, "previousStatus": { "type": [ "string", "null" ] }, "scheduledFor": { "type": [ "string", "null" ] }, "isBooking": { "type": "boolean" } }, "required": [ "entryId" ], "additionalProperties": false } }, "required": [ "id", "type", "schemaVersion", "occurredAt", "tenantId", "businessId", "queueId", "resourceId", "resourceVersion", "data" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions": { "get": { "operationId": "listWebhookSubscriptions", "summary": "List subscriptions owned by this credential", "description": "Requires webhooks:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "credentialId": { "type": "string" }, "kind": { "type": "string", "enum": [ "zapier", "custom" ] }, "destination": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } }, "businessId": { "type": [ "string", "null" ] }, "queueId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "pausedReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "secretRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "credentialId", "kind", "destination", "eventTypes", "businessId", "queueId", "status", "pausedReason", "createdAt", "updatedAt", "secretRotatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "limits": { "type": "object", "properties": { "subscriptions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "subscriptions" ], "additionalProperties": false } }, "required": [ "subscriptions", "nextCursor", "limits" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createWebhookSubscription", "summary": "Create a Zapier REST Hook subscription", "description": "Requires webhooks:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "default": "zapier", "type": "string", "enum": [ "zapier", "custom" ] }, "targetUrl": { "type": "string", "maxLength": 2048 }, "eventTypes": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } }, "businessId": { "type": "string", "minLength": 1, "maxLength": 128 }, "queueId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "targetUrl", "eventTypes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string" }, "credentialId": { "type": "string" }, "kind": { "type": "string", "enum": [ "zapier", "custom" ] }, "destination": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } }, "businessId": { "type": [ "string", "null" ] }, "queueId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "pausedReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "secretRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "credentialId", "kind", "destination", "eventTypes", "businessId", "queueId", "status", "pausedReason", "createdAt", "updatedAt", "secretRotatedAt" ], "additionalProperties": false }, "signingSecret": { "type": "string" } }, "required": [ "subscription", "signingSecret" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions/{id}": { "patch": { "operationId": "updateWebhookSubscription", "summary": "Pause, explicitly resume, or change event subscriptions", "description": "Idempotency-Key is required when resuming or changing event types. A pause remains available after plan or credential access ends. Resume starts after a new event watermark and never replays the disabled period.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] }, "eventTypes": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string" }, "credentialId": { "type": "string" }, "kind": { "type": "string", "enum": [ "zapier", "custom" ] }, "destination": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "waitlist.entry.created", "waitlist.entry.status_changed", "waitlist.entry.updated", "booking.created", "booking.rescheduled", "booking.cancelled" ] } }, "businessId": { "type": [ "string", "null" ] }, "queueId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "pausedReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "secretRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "credentialId", "kind", "destination", "eventTypes", "businessId", "queueId", "status", "pausedReason", "createdAt", "updatedAt", "secretRotatedAt" ], "additionalProperties": false } }, "required": [ "subscription" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteWebhookSubscription", "summary": "Disconnect a subscription", "description": "Requires webhooks:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Inspect redacted delivery attempts", "description": "Requires webhooks:read. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed", "cancelled" ] }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lastStatus": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "eventId", "status", "attemptCount", "nextAttemptAt", "lastStatus", "lastError", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "deliveries", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions/{id}/test": { "post": { "operationId": "testWebhookSubscription", "summary": "Queue a synthetic test without guest notifications", "description": "Requires webhooks:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string" } }, "required": [ "deliveryId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions/{id}/deliveries/{deliveryId}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Replay an eligible delivery with the same event ID", "description": "Requires webhooks:write. Resource restrictions and plan eligibility apply to every request.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean", "const": true } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } }, "/webhook-subscriptions/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret with a 24-hour verification overlap", "description": "Zapier subscriptions return ZAPIER_RECONNECT_REQUIRED: disable and re-enable the Zap so its stored signing secret is replaced. Standalone rotation is reserved for controlled custom endpoints, which remain disabled.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same value and request body for retries of one logical action.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "description": "Support request identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signingSecret": { "type": "string" }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "signingSecret", "previousSecretExpiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "402": { "description": "A plan upgrade, payment, or guest allowance is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient scope, resource access, or account eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found or not accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "Concurrent change or conflicting idempotency key. Fetch the current state before a new action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. Wait for Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } }, "503": { "description": "Writes or delivery are temporarily unavailable. Retry only after recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false } } } } } } } } } ```