{ "openapi": "3.1.0", "info": { "title": "Sutempo API", "version": "1.0.0", "description": "Sutempo is a booking engine for businesses that work by appointment (beauty, wellness, health, sport, education, trades, rentable spaces): catalogue, schedules, availability, bookings, clients, payments on the business's own Stripe account, transactional emails, external calendar sync and client self-service. Authenticate with an API key sent as a bearer token (Authorization: Bearer pk_...). Each operation lists in x-permissions-any-of the permissions a key needs (any one of them); keys are issued and revoked in the developer console. Writes accept an Idempotency-Key header: the same key with the same body returns the first result instead of acting twice. Availability: GET /v1/business-tenants/{tenantId}/availability/search returns the slots of several people, rooms or machines over up to 31 days in one call; availability and availability/days cover one resource. Weekday contract: ISO weekday index: 0 = Monday, 1 = Tuesday, 2 = Wednesday, 3 = Thursday, 4 = Friday, 5 = Saturday, 6 = Sunday. Availability offers only slots whose start is strictly after the server clock. Error bodies are {error: {code, message, correlationId, path?}}. Routes marked x-access=customer-token authenticate with the x-customer-access-token header (an account link adds ?appointment= on per-appointment routes); x-access=provider-webhook routes are authenticated by the provider signature; x-access=public routes take no credential and are throttled per client address.", "contact": { "name": "Sutempo", "url": "https://sutempo.com/developpeurs", "email": "bonjour@sutempo.com" } }, "servers": [ { "url": "https://sutempo.com", "description": "Production" }, { "url": "https://preprod.sutempo.com", "description": "Pre-production (test data only)" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pk__", "description": "API key issued in the developer console, restricted to explicit permissions and business tenants" }, "customerToken": { "type": "apiKey", "in": "header", "name": "x-customer-access-token", "description": "Signed appointment-management link token, or the account session sentinel for signed-in clients" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_INPUT", "AUTHENTICATION_REQUIRED", "PERMISSION_DENIED", "ORIGIN_DENIED", "NOT_FOUND", "CONFLICT", "PLAN_REQUIRED", "PAYMENT_REQUIRED", "TOO_MANY_AUTHENTICATION_FAILURES", "RATE_LIMITED", "QUOTA_EXCEEDED", "SERVICE_BUSY", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "correlationId": { "type": "string", "description": "Also returned in the x-correlation-id header; quote it when asking for support" }, "path": { "type": "string", "description": "The offending field, for INVALID_INPUT" } }, "required": [ "code", "message", "correlationId" ] } }, "required": [ "error" ] } }, "responses": { "InvalidInput": { "description": "Invalid request: a parameter or a body field is missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_INPUT", "message": "localDate must be a local date (YYYY-MM-DD)", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "AuthenticationRequired": { "description": "Missing, unknown or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "Authentication required", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "PermissionDenied": { "description": "The key lacks the permission, the business tenant or the plan this operation needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PERMISSION_DENIED", "message": "Permission denied", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "NotFound": { "description": "Unknown resource, or one this key may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "Conflict": { "description": "The request conflicts with the current state (slot taken, stale preview, plan required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "This time is no longer available", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "TooManyRequests": { "description": "Too many failed authentications or requests from this client; wait a minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "TOO_MANY_AUTHENTICATION_FAILURES", "message": "Too many attempts; wait a minute", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } }, "InternalError": { "description": "Unexpected error, or the service is momentarily busy (503)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal error", "correlationId": "3f0c9a52-7a51-4c1e-9d0b-6a2f4e8b1c77" } } } } } } }, "x-customer-locales": [ "fr", "en", "es", "pt" ], "paths": { "/health": { "get": { "operationId": "health", "summary": "Process liveness", "tags": [ "health" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false } }, "/ready": { "get": { "operationId": "readiness", "summary": "Readiness including PostgreSQL connectivity", "tags": [ "health" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false } }, "/v1/api-keys": { "post": { "operationId": "issueApiKey", "summary": "Issue a key whose permissions are a subset of the caller's; tenantIds limits its tenant grants to a subset of the caller's (default: all of them)", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "permissions": { "type": "array", "items": { "type": "string" } }, "tenantIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "Explicit tenant grants for the new key; every id must be granted to the caller, otherwise 403. Omitted copies every grant the caller holds; an empty list grants none." } }, "required": [ "label", "permissions" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "keys:write" ] }, "get": { "operationId": "listApiKeys", "summary": "List key metadata in the caller's scope (never secrets)", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "keys:read" ] } }, "/v1/merchant-accounts": { "post": { "operationId": "createMerchantAccount", "summary": "Give a business owner email sign-in to the merchant admin: mints a management key granted the listed businesses (a subset of the caller's grants) and binds it to the address; the key never leaves the server", "tags": [ "merchant-accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "tenantIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } }, "required": [ "email", "displayName", "tenantIds" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "keys:write" ] }, "get": { "operationId": "listMerchantAccounts", "summary": "Business owner accounts in the caller's scope: email, name, last sign-in (never credentials)", "tags": [ "merchant-accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "keys:read" ] } }, "/v1/api-keys/{keyId}": { "get": { "operationId": "getApiKey", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "keys:read" ] } }, "/v1/api-keys/{keyId}/rotate": { "post": { "operationId": "rotateApiKey", "summary": "Rotate a key the caller is allowed to delegate; the replacement never exceeds the caller", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 2592000 } }, "required": [ "overlapSeconds" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "keys:write" ] } }, "/v1/api-keys/{keyId}/revoke": { "post": { "operationId": "revokeApiKey", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "keys:write" ] } }, "/v1/usage": { "get": { "operationId": "getUsage", "tags": [ "usage" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "usage:read" ] } }, "/v1/developer-context": { "get": { "operationId": "getDeveloperContext", "tags": [ "developer-context" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "usage:read" ] } }, "/v1/billable-ping": { "post": { "operationId": "billablePing", "tags": [ "billable-ping" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": true, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants": { "post": { "operationId": "createBusinessTenant", "tags": [ "business-tenants" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "defaultLocale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "externalReference": { "type": [ "string", "null" ], "maxLength": 240 }, "metadata": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 40 }, "placeId": { "type": "string", "maxLength": 240 }, "category": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 200 }, "countryCode": { "type": "string", "pattern": "^[a-z]{2}$" }, "siteUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "releaseId": { "type": "string", "maxLength": 240 }, "status": { "type": "string", "enum": [ "ready", "published", "archived" ] }, "onboarding": { "type": "string", "enum": [ "done", "skipped" ] }, "onboardingTeam": { "type": "string", "enum": [ "solo", "team" ] }, "onboardingNature": { "type": "string", "enum": [ "individual", "group", "space" ] }, "onboardingRules": { "type": "string", "enum": [ "done" ] }, "onboardingNeeds": { "type": "string", "maxLength": 200, "pattern": "^[a-z,]*$" }, "onboardingPayment": { "type": "string", "enum": [ "onsite", "online" ] } }, "required": [], "additionalProperties": false } }, "required": [ "name", "defaultLocale" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "listBusinessTenants", "tags": [ "business-tenants" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] } }, "/v1/business-tenants/{tenantId}": { "patch": { "operationId": "updateBusinessTenant", "summary": "Rename the business, change its default language, set the public address served at / (null clears it; old / links stop working), or merge free metadata keys", "tags": [ "business-tenants" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "defaultLocale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "slug": { "type": [ "string", "null" ], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "minLength": 3, "maxLength": 40 }, "metadata": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 40 }, "placeId": { "type": "string", "maxLength": 240 }, "category": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 200 }, "countryCode": { "type": "string", "pattern": "^[a-z]{2}$" }, "siteUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "releaseId": { "type": "string", "maxLength": 240 }, "status": { "type": "string", "enum": [ "ready", "published", "archived" ] }, "onboarding": { "type": "string", "enum": [ "done", "skipped" ] }, "onboardingTeam": { "type": "string", "enum": [ "solo", "team" ] }, "onboardingNature": { "type": "string", "enum": [ "individual", "group", "space" ] }, "onboardingRules": { "type": "string", "enum": [ "done" ] }, "onboardingNeeds": { "type": "string", "maxLength": 200, "pattern": "^[a-z,]*$" }, "onboardingPayment": { "type": "string", "enum": [ "onsite", "online" ] } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "getBusinessTenant", "summary": "Public tenant profile: name and default locale", "tags": [ "business-tenants" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/locations": { "post": { "operationId": "createLocation", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "minLength": 1, "description": "IANA timezone" }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false }, "directionsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "accessInstructions": { "type": "string", "maxLength": 4000 }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false } }, "required": [ "name", "timezone" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "listLocations", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}": { "get": { "operationId": "getLocation", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] }, "patch": { "operationId": "updateLocation", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "minLength": 1, "description": "IANA timezone" }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false }, "directionsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "accessInstructions": { "type": "string", "maxLength": 4000 }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false } }, "required": [ "name", "timezone" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/services": { "post": { "operationId": "createService", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "durationOptions": { "type": [ "object", "null" ], "properties": { "minMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "maxMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "stepMinutes": { "type": "integer", "minimum": 5, "maximum": 720 } }, "required": [ "minMinutes", "maxMinutes", "stepMinutes" ], "additionalProperties": false, "description": "Variable duration: the client picks any multiple of stepMinutes between minMinutes and maxMinutes; the price scales pro rata from displayedPriceMinor for durationMinutes. Null means fixed duration." }, "displayedPriceMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "taxLabel": { "type": "string", "maxLength": 80 }, "policy": { "type": "object", "additionalProperties": true }, "categoryId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": { "type": "string", "maxLength": 4000 }, "preparationNotes": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "onlineBookable": { "type": "boolean", "description": "Off: staff can still book it, clients no longer see it online" }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 240 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 240 }, "agenda": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dedicated", "shared" ], "description": "dedicated: the offer owns a technical agenda (a room, a machine) provisioned and renamed with it. shared: the offer is delivered by the listed people, rooms or machines" }, "kind": { "type": "string", "enum": [ "space", "equipment" ], "description": "Kind at creation of the dedicated agenda; space by default, immutable afterwards" }, "resourceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "shared: existing resources that deliver the offer" }, "newResource": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "space", "equipment" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "kind", "displayName" ], "additionalProperties": false, "description": "shared: a resource created with the offer, e.g. the merchant themself for a solo practice" } }, "required": [ "mode" ], "additionalProperties": false, "description": "Availability of the offer, written in the same transaction as the offer. Omitted: the offer is created without eligibility (or keeps its current one) and can be associated later" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "Locations where the agenda makes the offer bookable; omitted means every active location" } }, "required": [ "name", "durationMinutes", "displayedPriceMinor", "currency", "taxLabel", "policy" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "listServices", "summary": "List services; ?locationId filters to services bookable at that location", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only the services offered at this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "includeArchived", "in": "query", "required": false, "description": "true or 1 also lists archived services", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/services/{serviceId}": { "get": { "operationId": "getService", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] }, "patch": { "operationId": "updateService", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "durationOptions": { "type": [ "object", "null" ], "properties": { "minMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "maxMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "stepMinutes": { "type": "integer", "minimum": 5, "maximum": 720 } }, "required": [ "minMinutes", "maxMinutes", "stepMinutes" ], "additionalProperties": false, "description": "Variable duration: the client picks any multiple of stepMinutes between minMinutes and maxMinutes; the price scales pro rata from displayedPriceMinor for durationMinutes. Null means fixed duration." }, "displayedPriceMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "taxLabel": { "type": "string", "maxLength": 80 }, "policy": { "type": "object", "additionalProperties": true }, "categoryId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": { "type": "string", "maxLength": 4000 }, "preparationNotes": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "onlineBookable": { "type": "boolean", "description": "Off: staff can still book it, clients no longer see it online" }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 240 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 240 }, "agenda": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dedicated", "shared" ], "description": "dedicated: the offer owns a technical agenda (a room, a machine) provisioned and renamed with it. shared: the offer is delivered by the listed people, rooms or machines" }, "kind": { "type": "string", "enum": [ "space", "equipment" ], "description": "Kind at creation of the dedicated agenda; space by default, immutable afterwards" }, "resourceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "shared: existing resources that deliver the offer" }, "newResource": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "space", "equipment" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "kind", "displayName" ], "additionalProperties": false, "description": "shared: a resource created with the offer, e.g. the merchant themself for a solo practice" } }, "required": [ "mode" ], "additionalProperties": false, "description": "Availability of the offer, written in the same transaction as the offer. Omitted: the offer is created without eligibility (or keeps its current one) and can be associated later" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "Locations where the agenda makes the offer bookable; omitted means every active location" } }, "required": [ "name", "durationMinutes", "displayedPriceMinor", "currency", "taxLabel", "policy" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/resources": { "post": { "operationId": "createResource", "tags": [ "resources" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "bio": { "type": "string", "maxLength": 4000 }, "kind": { "type": "string", "enum": [ "person", "space", "equipment" ], "description": "person (default), space or equipment" }, "hue": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10, "description": "Agenda colour 1–10; null derives one from the id" } }, "required": [ "displayName" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "listResources", "summary": "List active resources; ?locationId and ?serviceId filter to eligible ones", "tags": [ "resources" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only the resources that work at this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "serviceId", "in": "query", "required": false, "description": "Only the resources eligible for this service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/resources/{resourceId}": { "patch": { "operationId": "updateResource", "tags": [ "resources" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "bio": { "type": "string", "maxLength": 4000 }, "kind": { "type": "string", "enum": [ "person", "space", "equipment" ], "description": "person (default), space or equipment" }, "hue": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10, "description": "Agenda colour 1–10; null derives one from the id" } }, "required": [ "displayName" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/eligibility": { "post": { "operationId": "setEligibility", "tags": [ "eligibility" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [ "serviceId", "locationId", "resourceId" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "get": { "operationId": "getEligibility", "tags": [ "eligibility" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "serviceId", "in": "query", "required": true, "description": "Service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "locationId", "in": "query", "required": true, "description": "Location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "resourceId", "in": "query", "required": true, "description": "Resource", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] } }, "/v1/business-tenants/{tenantId}/eligibility/rows": { "get": { "operationId": "listEligibility", "tags": [ "eligibility" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] } }, "/v1/business-tenants/{tenantId}/eligibility/remove": { "post": { "operationId": "removeEligibility", "tags": [ "eligibility" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [ "serviceId", "locationId", "resourceId" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}/resources/{resourceId}/weekly-schedules": { "post": { "operationId": "createWeeklySchedule", "summary": "Recurring weekly window. weekday is ISO: 0 = Monday … 6 = Sunday", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "ISO weekday index: 0 = Monday, 1 = Tuesday, 2 = Wednesday, 3 = Thursday, 4 = Friday, 5 = Saturday, 6 = Sunday." }, "startLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "endLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "slotIntervalMinutes": { "type": "integer", "minimum": 5, "maximum": 240 } }, "required": [ "weekday", "startLocal", "endLocal", "slotIntervalMinutes" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "schedules:write" ] } }, "/v1/business-tenants/{tenantId}/schedule-exceptions": { "get": { "operationId": "listScheduleExceptions", "summary": "Exceptional days in [from, to] (local dates); optional ?locationId ?resourceId", "tags": [ "schedule-exceptions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First local date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } }, { "name": "to", "in": "query", "required": true, "description": "Last local date (YYYY-MM-DD), not before from", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "resourceId", "in": "query", "required": false, "description": "Only this resource", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "schedules:read" ] } }, "/v1/business-tenants/{tenantId}/schedule-exceptions/{exceptionId}": { "delete": { "operationId": "deleteScheduleException", "tags": [ "schedule-exceptions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "exceptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "schedules:write" ] } }, "/v1/business-tenants/{tenantId}/services/{serviceId}/archive": { "post": { "operationId": "archiveService", "summary": "Archive (archived: true) or restore a service; archived services keep their history but take no new bookings", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean" } }, "required": [ "archived" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/services/order": { "put": { "operationId": "reorderServices", "summary": "Set service positions from the given order", "tags": [ "services" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } }, "required": [ "ids" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}/archive": { "post": { "operationId": "archiveLocation", "summary": "Archive or restore a location", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean" } }, "required": [ "archived" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}/resources/{resourceId}/schedule-exceptions": { "post": { "operationId": "createScheduleException", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "startLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "endLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "slotIntervalMinutes": { "type": "integer", "minimum": 5, "maximum": 240 } }, "required": [ "localDate", "startLocal", "endLocal", "slotIntervalMinutes" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "schedules:write" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}/closures": { "post": { "operationId": "createClosure", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "resourceId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "localDate", "resourceId", "startLocal", "endLocal", "reason" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "schedules:write" ] } }, "/v1/business-tenants/{tenantId}/locations/{locationId}/resources/{resourceId}/schedule-day": { "get": { "operationId": "getScheduleDay", "tags": [ "locations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "localDate", "in": "query", "required": true, "description": "Local date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } } ], "x-billable": false, "x-permissions-any-of": [ "schedules:read" ] } }, "/v1/business-tenants/{tenantId}/availability": { "get": { "operationId": "getAvailability", "summary": "Future slots only: a slot is offered when its start is after the server clock. ?durationMinutes picks one of a variable-duration service's offered lengths", "tags": [ "availability" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "required": true, "description": "Location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "5b1f4c1e-8d2a-4c67-9a3e-2f6d0b7c9a11" }, { "name": "serviceId", "in": "query", "required": true, "description": "Service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "0c6e2a9b-3f41-4d8e-b7a2-6e9d1c4f5b22" }, { "name": "resourceId", "in": "query", "required": true, "description": "Person, room or machine", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "7d3a1e5c-9b24-4f60-8c1d-3a5e7b9d2c33" }, { "name": "localDate", "in": "query", "required": true, "description": "Local date at the location (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "example": "2026-10-01" }, { "name": "durationMinutes", "in": "query", "required": false, "description": "Variable-duration services only: one of the offered lengths, in minutes; omitted means the base duration", "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/availability/days": { "get": { "operationId": "getAvailableDays", "summary": "The local dates of [?from, ?to] (YYYY-MM-DD, at most 62 days) on which ?resourceId offers at least one slot of ?serviceId at ?locationId, for a month view; ?durationMinutes as for availability. Online keys see the booking rules applied (lead time, horizon)", "tags": [ "availability" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "required": true, "description": "Location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "serviceId", "in": "query", "required": true, "description": "Service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "resourceId", "in": "query", "required": true, "description": "Person, room or machine", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "from", "in": "query", "required": true, "description": "First local date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } }, { "name": "to", "in": "query", "required": true, "description": "Last local date (YYYY-MM-DD), at most 62 days after from", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } }, { "name": "durationMinutes", "in": "query", "required": false, "description": "Variable-duration services only: one of the offered lengths, in minutes; omitted means the base duration", "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/availability/search": { "get": { "operationId": "searchAvailability", "summary": "Every offered slot of ?serviceId at ?locationId over the local dates [?from, ?to] (at most 31 days) for several people, rooms or machines in one call, sorted by start. ?resourceIds omitted means every resource eligible for the service there; at most 10 resources and 155 resource-days. Same rules as availability: future slots only, and online keys see the booking rules applied (lead time, horizon)", "tags": [ "availability" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "to": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "resourceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": "The resources searched, in the order given" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "localStart": { "type": "string", "description": "Local wall time at the location" }, "locationTimezone": { "type": "string", "description": "IANA timezone" }, "maxDurationMinutes": { "type": "integer", "description": "Longest booking that may start here" } }, "required": [ "resourceId", "localDate", "startsAt", "endsAt", "localStart", "locationTimezone", "maxDurationMinutes" ], "additionalProperties": false } } }, "required": [ "from", "to", "resourceIds", "slots" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "serviceId", "in": "query", "required": true, "description": "Service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "0c6e2a9b-3f41-4d8e-b7a2-6e9d1c4f5b22" }, { "name": "locationId", "in": "query", "required": true, "description": "Location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "5b1f4c1e-8d2a-4c67-9a3e-2f6d0b7c9a11" }, { "name": "from", "in": "query", "required": true, "description": "First local date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": true, "description": "Last local date (YYYY-MM-DD), at most 31 days after from", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "example": "2026-10-07" }, { "name": "resourceIds", "in": "query", "required": false, "description": "Comma-separated resource ids (at most 10); omitted means every eligible resource", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?:,[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}){0,9}$" }, "example": "7d3a1e5c-9b24-4f60-8c1d-3a5e7b9d2c33,a8e4c2f6-1d35-4b79-9e0a-4c6d8f1b3d44" }, { "name": "durationMinutes", "in": "query", "required": false, "description": "Variable-duration services only: one of the offered lengths, in minutes; omitted means the base duration", "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/customers": { "post": { "operationId": "createCustomer", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "marketingState": { "type": "string", "enum": [ "unknown", "subscribed", "unsubscribed" ] }, "notes": { "type": "string", "maxLength": 4000 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "consents": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "phone", "sms" ] }, "state": { "type": "string", "enum": [ "granted", "denied", "withdrawn" ] }, "source": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "channel", "state", "source" ], "additionalProperties": false } } }, "required": [ "displayName", "email", "phone", "marketingState", "consents" ], "additionalProperties": false }, "example": { "displayName": "Inês Costa", "email": "ines@example.com", "phone": null, "marketingState": "unknown", "consents": [ { "channel": "email", "state": "granted", "source": "online-booking" } ] } } } }, "x-billable": false, "x-permissions-any-of": [ "customers:write", "widget:book" ] }, "get": { "operationId": "listCustomers", "summary": "The customer base: non-erased customers with appointment statistics; ?query matches name, email or phone; ?limit (max 200) and ?offset page through", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "query", "in": "query", "required": false, "description": "Search on name, e-mail or phone", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "type": "string", "pattern": "^[0-9]{1,6}$" } } ], "x-billable": false, "x-permissions-any-of": [ "customers:read" ] } }, "/v1/business-tenants/{tenantId}/customers/{customerId}": { "get": { "operationId": "getCustomer", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "customers:read" ] }, "patch": { "operationId": "updateCustomer", "summary": "Edit the contact and notes the business keeps about a customer; erased customers cannot be edited", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "marketingState": { "type": "string", "enum": [ "unknown", "subscribed", "unsubscribed" ] }, "notes": { "type": "string", "maxLength": 4000 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "customers:write" ] } }, "/v1/business-tenants/{tenantId}/customers/{customerId}/appointments": { "get": { "operationId": "listCustomerAppointments", "summary": "Every appointment of one customer, most recent first (at most 200)", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/customers/{customerId}/erase": { "post": { "operationId": "eraseCustomer", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "customers:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/bundle": { "post": { "operationId": "bookAppointmentBundle", "summary": "Confirm all service lines atomically or leave no bookings", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startsAt": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "customerId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "override": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 4000 }, "payment": { "type": "string", "enum": [ "online", "on_site" ], "description": "on_site: paid at the business, confirmed at once without online payment; online (default): a paid line waits for its online payment" } }, "required": [ "locationId", "serviceId", "resourceId", "startsAt" ], "additionalProperties": false } } }, "required": [ "lines" ], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/hold": { "post": { "operationId": "holdAppointment", "summary": "Hold an offered future slot for five minutes; confirmAppointment then books it", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startsAt": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720, "description": "For a variable-duration service: the length booked; omitted means the service's base duration" }, "customerId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$", "description": "The visitor's locale; drives emails and the self-service portal" }, "override": { "type": "boolean", "description": "Back office only: book outside opening hours; overlaps are still refused" }, "notes": { "type": "string", "maxLength": 4000, "description": "Internal note on the visit" }, "captchaToken": { "type": "string", "maxLength": 2048, "description": "Cloudflare Turnstile token; demanded only when the platform is configured for it, and only from a key that cannot write bookings" } }, "required": [ "locationId", "serviceId", "resourceId", "startsAt" ], "additionalProperties": false }, "example": { "locationId": "5b1f4c1e-8d2a-4c67-9a3e-2f6d0b7c9a11", "serviceId": "0c6e2a9b-3f41-4d8e-b7a2-6e9d1c4f5b22", "resourceId": "7d3a1e5c-9b24-4f60-8c1d-3a5e7b9d2c33", "startsAt": "2026-10-01T09:00:00Z", "customerId": "e2b9d7a1-6c48-4f13-a5d6-8b0e2c4f6a55" } } } }, "x-billable": true, "x-permissions-any-of": [ "bookings:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}": { "patch": { "operationId": "updateAppointmentNotes", "summary": "Replace the internal note on an appointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 4000 } }, "required": [ "notes" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] }, "get": { "operationId": "getAppointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/check-in": { "post": { "operationId": "checkInAppointment", "summary": "Mark the client as arrived (arrived: false clears it)", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "arrived": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/complete": { "post": { "operationId": "completeAppointment", "summary": "Mark the visit as done (done: false reopens it)", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/resend": { "post": { "operationId": "resendAppointmentEmail", "summary": "Queue the confirmation email again", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "notifications:write" ] } }, "/v1/business-tenants/{tenantId}/blocks": { "post": { "operationId": "createTimeBlock", "summary": "Block time for a person or a room (no client)", "tags": [ "blocks" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "locationId", "resourceId", "startsAt", "endsAt" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] }, "get": { "operationId": "listTimeBlocks", "summary": "Blocked time overlapping [from, to); optional ?resourceId ?locationId", "tags": [ "blocks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Start of the range (ISO 8601 instant)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "End of the range; at most 92 days after from", "schema": { "type": "string", "format": "date-time" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "resourceId", "in": "query", "required": false, "description": "Only this resource", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/blocks/{blockId}": { "delete": { "operationId": "deleteTimeBlock", "tags": [ "blocks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "blockId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/booking-rules": { "get": { "operationId": "getBookingRules", "summary": "Online booking rules: lead time, horizon, what clients may change", "tags": [ "booking-rules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] }, "put": { "operationId": "updateBookingRules", "tags": [ "booking-rules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onlineEnabled": { "type": "boolean" }, "minLeadMinutes": { "type": "integer", "minimum": 0, "maximum": 20160 }, "horizonDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "clientCancelHours": { "type": "integer", "minimum": 0, "maximum": 720 }, "clientReschedule": { "type": "boolean" }, "anyStaff": { "type": "boolean" }, "slotGranularityMinutes": { "type": [ "integer", "null" ], "enum": [ 5, 10, 15, 20, 30, 60, null ] }, "autoConfirm": { "type": "boolean" }, "requirePhone": { "type": "boolean" }, "allowNote": { "type": "boolean" }, "maxDailyBookingsPerPerson": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "requireCancellationReason": { "type": "boolean" }, "autoAssignResource": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/blocked-contacts": { "get": { "operationId": "listBlockedContacts", "summary": "Emails and phone numbers this business refuses to serve online, most recent first", "tags": [ "blocked-contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] }, "post": { "operationId": "createBlockedContact", "summary": "Refuse online booking to an email address or a phone number; the back office may still book them. Blocking the same value twice updates the entry", "tags": [ "blocked-contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "kind", "value" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/blocked-contacts/{blockedContactId}": { "delete": { "operationId": "deleteBlockedContact", "tags": [ "blocked-contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "blockedContactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/allowed-origins": { "get": { "operationId": "listAllowedOrigins", "summary": "Third-party sites allowed to call the API cross-origin with this business's public booking key (the Pro widget). Honoured only while the business is on Pro; kept, not honoured, on Solo", "tags": [ "allowed-origins" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "origin": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "origin", "createdAt" ], "additionalProperties": false } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] }, "post": { "operationId": "createAllowedOrigin", "summary": "Allow one exact origin (scheme, host, port) for the widget: https only, no IP address, no wildcard, at most 10 per business; a pasted URL keeps only its origin, adding it twice returns the existing entry. Requires Pro", "tags": [ "allowed-origins" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "origin": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "origin", "createdAt" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "origin" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/allowed-origins/{allowedOriginId}": { "delete": { "operationId": "deleteAllowedOrigin", "summary": "Stop allowing this origin; takes effect on every instance within 30 seconds", "tags": [ "allowed-origins" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "allowedOriginId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/blueprint/versions": { "get": { "operationId": "listBlueprintVersions", "summary": "Applied configuration versions, most recent first; ?limit ?before", "tags": [ "blueprint" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 20 by default", "schema": { "type": "string", "pattern": "^[0-9]{1,3}$" } }, { "name": "before", "in": "query", "required": false, "description": "Only versions older than this version number", "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] } }, "/v1/business-tenants/{tenantId}/notifications/test": { "post": { "operationId": "sendTestNotification", "summary": "Send a sample email of the given kind to an address of yours, rendered exactly as the worker would with your saved or draft settings", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email", "maxLength": 320 }, "kind": { "type": "string", "enum": [ "confirmation", "reminder", "rescheduled", "cancelled", "instructions", "thank_you", "rebook", "review", "request_received", "request_declined", "request_expired", "pack_receipt" ] }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "replyToEmail": { "type": [ "string", "null" ], "maxLength": 320 }, "senderName": { "type": [ "string", "null" ], "maxLength": 120 }, "reminderHoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 }, "reminderEnabled": { "type": "boolean", "description": "Send the reminder before the appointment; defaults to true" }, "logoUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "Email-only logo override (https); null inherits the profile" }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Email-only button colour override; null inherits the profile" }, "signature": { "type": "string", "maxLength": 600, "description": "Closing plain text under the sign-off" }, "texts": { "type": "object", "properties": { "confirmation": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "reminder": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rescheduled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "cancelled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "instructions": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "thank_you": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rebook": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "review": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_received": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_declined": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_expired": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "pack_receipt": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" } }, "required": [], "additionalProperties": false, "description": "Intro text per email; empty means the localized default" }, "instructions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Practical instructions before the appointment" }, "thankYou": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursAfter": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Thank-you note after the appointment" }, "rebook": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysAfter": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [], "additionalProperties": false, "description": "Invitation to book again; sent only to clients whose marketing state is subscribed at send time" } }, "required": [], "additionalProperties": false, "description": "Automatic emails sent by the platform on behalf of the business. The From address is platform configuration; the business sets the sender name and Reply-To." } }, "required": [ "to" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "notifications:write" ] } }, "/v1/business-tenants/{tenantId}/notifications/preview": { "post": { "operationId": "previewNotificationEmail", "summary": "Render one email (subject, html, text) on a sample appointment built from your catalogue, with saved or draft settings; nothing is queued or sent", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "from": { "type": "object" }, "replyTo": { "type": [ "string", "null" ] } }, "required": [ "subject", "html", "text" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "confirmation", "reminder", "rescheduled", "cancelled", "instructions", "thank_you", "rebook", "review", "request_received", "request_declined", "request_expired", "pack_receipt" ] }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "replyToEmail": { "type": [ "string", "null" ], "maxLength": 320 }, "senderName": { "type": [ "string", "null" ], "maxLength": 120 }, "reminderHoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 }, "reminderEnabled": { "type": "boolean", "description": "Send the reminder before the appointment; defaults to true" }, "logoUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "Email-only logo override (https); null inherits the profile" }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Email-only button colour override; null inherits the profile" }, "signature": { "type": "string", "maxLength": 600, "description": "Closing plain text under the sign-off" }, "texts": { "type": "object", "properties": { "confirmation": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "reminder": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rescheduled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "cancelled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "instructions": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "thank_you": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rebook": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "review": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_received": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_declined": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_expired": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "pack_receipt": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" } }, "required": [], "additionalProperties": false, "description": "Intro text per email; empty means the localized default" }, "instructions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Practical instructions before the appointment" }, "thankYou": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursAfter": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Thank-you note after the appointment" }, "rebook": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysAfter": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [], "additionalProperties": false, "description": "Invitation to book again; sent only to clients whose marketing state is subscribed at send time" } }, "required": [], "additionalProperties": false, "description": "Automatic emails sent by the platform on behalf of the business. The From address is platform configuration; the business sets the sender name and Reply-To." } }, "required": [ "kind" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "notifications:read" ] } }, "/v1/business-tenants/{tenantId}/notifications/{deliveryId}/retry": { "post": { "operationId": "retryNotification", "summary": "Put a failed or skipped email back in the queue: the same delivery, with its history, idempotency key and frozen payload; refused when the provider was already called and a byte-identical replay can no longer be guaranteed (see retryBlockedReason). Status, timing and consent are re-checked before sending", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "notifications:write" ] } }, "/v1/email/unsubscribe": { "get": { "operationId": "unsubscribeEmail", "summary": "Unsubscribe page for a business's commercial emails, reached from the opaque token carried in the email (?t=). GET only shows a confirmation form and changes nothing (safe for link scanners)", "tags": [ "email" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "string", "description": "HTML page" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "t", "in": "query", "required": true, "description": "Signed token from the e-mail link", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } } ], "x-billable": false, "x-access": "public" }, "post": { "operationId": "confirmEmailUnsubscribe", "summary": "Performs the unsubscription for the token in ?t= (submitted by the confirmation form): every customer record of the business sharing the address is set to unsubscribed; idempotent, renders the result page", "tags": [ "email" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "string", "description": "HTML page" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "t", "in": "query", "required": true, "description": "Signed token from the e-mail link", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } } ], "x-billable": false, "x-access": "public" } }, "/v1/business-tenants/{tenantId}/reports/summary": { "get": { "operationId": "getReportSummary", "summary": "Period aggregates: totals, by day, by person, by service, by hour", "tags": [ "reports" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Start of the period (ISO 8601 instant)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "End of the period", "schema": { "type": "string", "format": "date-time" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/appointments": { "get": { "operationId": "listAppointments", "summary": "Appointments starting in [from, to); optional ?locationId", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Start of the range, inclusive (ISO 8601 instant)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "End of the range, exclusive; at most 92 days after from", "schema": { "type": "string", "format": "date-time" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/confirm": { "post": { "operationId": "confirmAppointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": true, "x-permissions-any-of": [ "bookings:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/reschedule": { "post": { "operationId": "rescheduleAppointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startsAt": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer", "minimum": 15, "maximum": 720 } }, "required": [ "locationId", "resourceId", "startsAt" ], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/cancel": { "post": { "operationId": "cancelAppointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": true, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/release": { "post": { "operationId": "releaseAppointmentHold", "summary": "Let go of a hold before it runs out (the visitor left the payment): it ends as expired and the slot is offered again. A public booking key must present the releaseToken returned with the hold; a paid or confirmed booking is never released", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseToken": { "type": "string", "maxLength": 1000 } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "bookings:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/no-show": { "post": { "operationId": "noShowAppointment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": true, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/webhook-subscriptions": { "post": { "operationId": "createWebhookSubscription", "tags": [ "webhook-subscriptions" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpointUrl": { "type": "string", "format": "uri", "maxLength": 2000 } }, "required": [ "endpointUrl" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "webhooks:write" ] } }, "/v1/webhook-subscriptions": { "get": { "operationId": "listWebhookSubscriptions", "tags": [ "webhook-subscriptions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "webhooks:read" ] } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Recent deliveries for the caller's tenants; optional ?subscriptionId", "tags": [ "webhook-deliveries" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "subscriptionId", "in": "query", "required": false, "description": "Only the deliveries of this subscription", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "webhooks:read" ] } }, "/v1/webhook-deliveries/dead-letters": { "get": { "operationId": "listWebhookDeadLetters", "tags": [ "webhook-deliveries" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-permissions-any-of": [ "webhooks:read" ] } }, "/v1/business-tenants/{tenantId}/blueprint/current": { "get": { "operationId": "getCurrentBlueprint", "summary": "The tenant's live configuration as a complete blueprint document", "tags": [ "blueprint" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "businessTenantId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "minLength": 1, "description": "IANA timezone such as Europe/Lisbon" }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false, "description": "Structured postal address." }, "directionsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "accessInstructions": { "type": "string", "maxLength": 4000 }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "name", "timezone" ], "additionalProperties": false, "description": "A physical place where services are delivered, with its practical information." } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Groups services on the booking page." } }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720, "description": "Base duration; with durationOptions it is the reference the price is quoted for" }, "durationOptions": { "type": [ "object", "null" ], "properties": { "minMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "maxMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "stepMinutes": { "type": "integer", "minimum": 5, "maximum": 720 } }, "required": [ "minMinutes", "maxMinutes", "stepMinutes" ], "additionalProperties": false, "description": "Variable duration: the client picks any multiple of stepMinutes between minMinutes and maxMinutes; the price scales pro rata from displayedPriceMinor for durationMinutes. Null means fixed duration." }, "displayedPriceMinor": { "type": "integer", "minimum": 0, "description": "Displayed price in minor currency units (cents)" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code" }, "taxLabel": { "type": "string", "maxLength": 80 }, "policy": { "type": "object", "additionalProperties": true, "description": "Free-form service policy such as {\"cancellationHours\": 24}" }, "categoryId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": { "type": "string", "maxLength": 4000 }, "preparationNotes": { "type": "string", "maxLength": 4000, "description": "What the client should know or do before the appointment" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "description": "Preparation time blocked before each booking; the client is neither shown nor charged it" }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "description": "Cleanup time blocked after each booking; the client is neither shown nor charged it" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "name", "durationMinutes", "displayedPriceMinor", "currency", "taxLabel", "policy" ], "additionalProperties": false, "description": "A bookable service with immutable snapshot fields and presentation content." } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "kind": { "type": "string", "enum": [ "person", "space", "equipment" ], "description": "person (staff), space (room, cabin) or equipment" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "bio": { "type": "string", "maxLength": 4000 }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "displayName" ], "additionalProperties": false, "description": "A person or room that delivers services. Removing one is destructive when it has future bookings." } }, "eligibility": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" } }, "required": [ "serviceId", "locationId", "resourceId" ], "additionalProperties": false, "description": "Declares that a resource may deliver a service at a location." } }, "workingWindows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "ISO weekday index: 0 = Monday, 1 = Tuesday, 2 = Wednesday, 3 = Thursday, 4 = Friday, 5 = Saturday, 6 = Sunday." }, "startLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "endLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "slotIntervalMinutes": { "type": "integer", "minimum": 5, "maximum": 240 } }, "required": [ "id", "locationId", "resourceId", "weekday", "startLocal", "endLocal", "slotIntervalMinutes" ], "additionalProperties": false, "description": "A recurring weekly opening window for one resource at one location." } }, "closures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "Resource UUID, or null for the whole location" }, "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "startLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "id", "locationId", "resourceId", "localDate", "startLocal", "endLocal", "reason" ], "additionalProperties": false, "description": "A one-off closure. Both times null closes the entire day." } }, "profile": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "logoUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "onPrimaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "backgroundColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "surfaceColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "textColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "bodyFont": { "type": "string", "maxLength": 100 }, "displayFont": { "type": "string", "maxLength": 100 }, "radius": { "type": "integer", "minimum": 0, "maximum": 32 }, "tone": { "type": "string", "enum": [ "formal", "friendly" ] } }, "required": [], "additionalProperties": false, "description": "Visual identity applied to the booking page, emails and client portal. Colour pairs must reach WCAG AA contrast." }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "page": { "type": "object", "properties": { "industry": { "type": "string", "enum": [ "general", "beauty", "barber", "wellness", "health", "fitness", "spaces", "education", "consulting", "crafts", "pets", "auto", "home" ] }, "vocabulary": { "type": "string", "enum": [ "service", "treatment", "consultation", "class", "space", "appointment" ], "description": "The word the business uses for what it sells; falls back to the one implied by industry" }, "serviceLabel": { "type": "string", "maxLength": 60 }, "showCategories": { "type": "boolean" }, "showPacks": { "type": "boolean" }, "packsTitle": { "type": "string", "maxLength": 100 }, "packsDescription": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "tagline": { "type": "string", "maxLength": 200 }, "coverUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "reviewCount": { "type": [ "integer", "null" ], "minimum": 0 }, "reviewsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "socialUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "about": { "type": "string", "maxLength": 4000 }, "theme": { "type": "string", "enum": [ "system", "light", "dark" ] } }, "required": [], "additionalProperties": false, "description": "Hosted business page: cover image, tagline and the review score the business displays." }, "policies": { "type": "object", "properties": { "cancellationHours": { "type": "integer", "minimum": 0, "maximum": 720 }, "cancellationText": { "type": "string", "maxLength": 4000 } }, "required": [], "additionalProperties": false }, "locales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "description": "Locales the booking page and emails are offered in; content is translated once and persisted" } }, "required": [], "additionalProperties": false, "description": "Tenant-wide presentation, contact and policy settings." }, "payments": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "full", "deposit_percent", "deposit_fixed" ] }, "depositPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "depositFixedMinor": { "type": "integer", "minimum": 0 }, "holdMinutes": { "type": "integer", "minimum": 30, "maximum": 1440, "description": "How long a slot stays held while the client pays" }, "refundOnCancellation": { "type": "string", "enum": [ "always", "outside_window", "never" ] } }, "required": [], "additionalProperties": false, "description": "Payment or deposit collected at booking. Provider credentials are platform configuration, never tenant data." }, "notifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "replyToEmail": { "type": [ "string", "null" ], "maxLength": 320 }, "senderName": { "type": [ "string", "null" ], "maxLength": 120 }, "reminderHoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 }, "reminderEnabled": { "type": "boolean", "description": "Send the reminder before the appointment; defaults to true" }, "logoUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "Email-only logo override (https); null inherits the profile" }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Email-only button colour override; null inherits the profile" }, "signature": { "type": "string", "maxLength": 600, "description": "Closing plain text under the sign-off" }, "texts": { "type": "object", "properties": { "confirmation": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "reminder": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rescheduled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "cancelled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "instructions": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "thank_you": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rebook": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "review": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_received": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_declined": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_expired": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "pack_receipt": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" } }, "required": [], "additionalProperties": false, "description": "Intro text per email; empty means the localized default" }, "instructions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Practical instructions before the appointment" }, "thankYou": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursAfter": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Thank-you note after the appointment" }, "rebook": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysAfter": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [], "additionalProperties": false, "description": "Invitation to book again; sent only to clients whose marketing state is subscribed at send time" } }, "required": [], "additionalProperties": false, "description": "Automatic emails sent by the platform on behalf of the business. The From address is platform configuration; the business sets the sender name and Reply-To." }, "packs": { "type": "array", "items": { "type": "object", "properties": { "published": { "type": "boolean", "description": "Explicit public sale visibility. Defaults to false; existing purchases are unaffected." }, "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "priceMinor": { "type": "integer", "minimum": 0, "description": "Sale price in minor units (cents); 0 for packs that are only granted" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitKind": { "type": "string", "enum": [ "sessions", "value" ], "description": "sessions (default): one credit pays one appointment. value: units is an amount in minor currency units and a booking debits its displayed price" }, "units": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Credits included: a count of appointments (sessions, at most 1000) or an amount in minor units (value)" }, "validityDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Days after activation before unused credits expire; null never expires" }, "serviceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Services a credit may pay for; empty means every service" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Locations a credit may be used at; empty means every location" }, "active": { "type": "boolean", "description": "Inactive packs stay redeemable but are no longer sold or granted" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "name", "priceMinor", "currency", "units" ], "additionalProperties": false, "description": "A prepaid pack of credits. Removing a pack from the document deactivates it; purchases keep their credits." } }, "reviewRequests": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 0, "maximum": 336, "description": "Hours after the appointment ends before the request is sent" }, "googleReviewUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "The business's Google review link; required to send" }, "cooldownDays": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Minimum days between two requests to the same client" } }, "required": [], "additionalProperties": false, "description": "Automatic review request email after completed appointments. Every eligible client is asked; there is no gating or sentiment filter." }, "policies": { "type": "object", "additionalProperties": true }, "enabledCapabilities": { "type": "array", "items": { "type": "string", "enum": [ "appointments", "payments", "notifications", "calendar_sync", "team", "spaces", "equipment", "packs", "group_sessions", "review_requests" ] }, "description": "Optional modules to switch on: team, spaces, equipment, packs, group_sessions, review_requests. Switching off keeps data. appointments, payments, notifications and calendar_sync are informational and follow their own settings." } }, "required": [ "schemaVersion", "businessTenantId", "locations", "services", "resources", "eligibility", "workingWindows", "closures", "policies", "enabledCapabilities" ], "additionalProperties": false, "description": "Complete configuration-only description of one business tenant." } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "blueprints:read" ] } }, "/v1/business-tenants/{tenantId}/blueprint/previews": { "post": { "operationId": "previewBlueprintChanges", "summary": "Validate a blueprint and return the diff and destructive impacts (requires idempotency-key)", "tags": [ "blueprint" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blueprint": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "businessTenantId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "minLength": 1, "description": "IANA timezone such as Europe/Lisbon" }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false, "description": "Structured postal address." }, "directionsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "accessInstructions": { "type": "string", "maxLength": 4000 }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "name", "timezone" ], "additionalProperties": false, "description": "A physical place where services are delivered, with its practical information." } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Groups services on the booking page." } }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 720, "description": "Base duration; with durationOptions it is the reference the price is quoted for" }, "durationOptions": { "type": [ "object", "null" ], "properties": { "minMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "maxMinutes": { "type": "integer", "minimum": 5, "maximum": 720 }, "stepMinutes": { "type": "integer", "minimum": 5, "maximum": 720 } }, "required": [ "minMinutes", "maxMinutes", "stepMinutes" ], "additionalProperties": false, "description": "Variable duration: the client picks any multiple of stepMinutes between minMinutes and maxMinutes; the price scales pro rata from displayedPriceMinor for durationMinutes. Null means fixed duration." }, "displayedPriceMinor": { "type": "integer", "minimum": 0, "description": "Displayed price in minor currency units (cents)" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code" }, "taxLabel": { "type": "string", "maxLength": 80 }, "policy": { "type": "object", "additionalProperties": true, "description": "Free-form service policy such as {\"cancellationHours\": 24}" }, "categoryId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "description": { "type": "string", "maxLength": 4000 }, "preparationNotes": { "type": "string", "maxLength": 4000, "description": "What the client should know or do before the appointment" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "description": "Preparation time blocked before each booking; the client is neither shown nor charged it" }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "description": "Cleanup time blocked after each booking; the client is neither shown nor charged it" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "name", "durationMinutes", "displayedPriceMinor", "currency", "taxLabel", "policy" ], "additionalProperties": false, "description": "A bookable service with immutable snapshot fields and presentation content." } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "kind": { "type": "string", "enum": [ "person", "space", "equipment" ], "description": "person (staff), space (room, cabin) or equipment" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "bio": { "type": "string", "maxLength": 4000 }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } }, "required": [ "id", "displayName" ], "additionalProperties": false, "description": "A person or room that delivers services. Removing one is destructive when it has future bookings." } }, "eligibility": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" } }, "required": [ "serviceId", "locationId", "resourceId" ], "additionalProperties": false, "description": "Declares that a resource may deliver a service at a location." } }, "workingWindows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "ISO weekday index: 0 = Monday, 1 = Tuesday, 2 = Wednesday, 3 = Thursday, 4 = Friday, 5 = Saturday, 6 = Sunday." }, "startLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "endLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "slotIntervalMinutes": { "type": "integer", "minimum": 5, "maximum": 240 } }, "required": [ "id", "locationId", "resourceId", "weekday", "startLocal", "endLocal", "slotIntervalMinutes" ], "additionalProperties": false, "description": "A recurring weekly opening window for one resource at one location." } }, "closures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "resourceId": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "Resource UUID, or null for the whole location" }, "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "startLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endLocal": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "id", "locationId", "resourceId", "localDate", "startLocal", "endLocal", "reason" ], "additionalProperties": false, "description": "A one-off closure. Both times null closes the entire day." } }, "profile": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "logoUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "onPrimaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "backgroundColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "surfaceColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "textColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "bodyFont": { "type": "string", "maxLength": 100 }, "displayFont": { "type": "string", "maxLength": 100 }, "radius": { "type": "integer", "minimum": 0, "maximum": 32 }, "tone": { "type": "string", "enum": [ "formal", "friendly" ] } }, "required": [], "additionalProperties": false, "description": "Visual identity applied to the booking page, emails and client portal. Colour pairs must reach WCAG AA contrast." }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "page": { "type": "object", "properties": { "industry": { "type": "string", "enum": [ "general", "beauty", "barber", "wellness", "health", "fitness", "spaces", "education", "consulting", "crafts", "pets", "auto", "home" ] }, "vocabulary": { "type": "string", "enum": [ "service", "treatment", "consultation", "class", "space", "appointment" ], "description": "The word the business uses for what it sells; falls back to the one implied by industry" }, "serviceLabel": { "type": "string", "maxLength": 60 }, "showCategories": { "type": "boolean" }, "showPacks": { "type": "boolean" }, "packsTitle": { "type": "string", "maxLength": 100 }, "packsDescription": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "tagline": { "type": "string", "maxLength": 200 }, "coverUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "reviewCount": { "type": [ "integer", "null" ], "minimum": 0 }, "reviewsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "socialUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "about": { "type": "string", "maxLength": 4000 }, "theme": { "type": "string", "enum": [ "system", "light", "dark" ] } }, "required": [], "additionalProperties": false, "description": "Hosted business page: cover image, tagline and the review score the business displays." }, "policies": { "type": "object", "properties": { "cancellationHours": { "type": "integer", "minimum": 0, "maximum": 720 }, "cancellationText": { "type": "string", "maxLength": 4000 } }, "required": [], "additionalProperties": false }, "locales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "description": "Locales the booking page and emails are offered in; content is translated once and persisted" } }, "required": [], "additionalProperties": false, "description": "Tenant-wide presentation, contact and policy settings." }, "payments": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "full", "deposit_percent", "deposit_fixed" ] }, "depositPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "depositFixedMinor": { "type": "integer", "minimum": 0 }, "holdMinutes": { "type": "integer", "minimum": 30, "maximum": 1440, "description": "How long a slot stays held while the client pays" }, "refundOnCancellation": { "type": "string", "enum": [ "always", "outside_window", "never" ] } }, "required": [], "additionalProperties": false, "description": "Payment or deposit collected at booking. Provider credentials are platform configuration, never tenant data." }, "notifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "replyToEmail": { "type": [ "string", "null" ], "maxLength": 320 }, "senderName": { "type": [ "string", "null" ], "maxLength": 120 }, "reminderHoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 }, "reminderEnabled": { "type": "boolean", "description": "Send the reminder before the appointment; defaults to true" }, "logoUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "Email-only logo override (https); null inherits the profile" }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Email-only button colour override; null inherits the profile" }, "signature": { "type": "string", "maxLength": 600, "description": "Closing plain text under the sign-off" }, "texts": { "type": "object", "properties": { "confirmation": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "reminder": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rescheduled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "cancelled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "instructions": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "thank_you": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rebook": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "review": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_received": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_declined": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_expired": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "pack_receipt": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" } }, "required": [], "additionalProperties": false, "description": "Intro text per email; empty means the localized default" }, "instructions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Practical instructions before the appointment" }, "thankYou": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursAfter": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Thank-you note after the appointment" }, "rebook": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysAfter": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [], "additionalProperties": false, "description": "Invitation to book again; sent only to clients whose marketing state is subscribed at send time" } }, "required": [], "additionalProperties": false, "description": "Automatic emails sent by the platform on behalf of the business. The From address is platform configuration; the business sets the sender name and Reply-To." }, "packs": { "type": "array", "items": { "type": "object", "properties": { "published": { "type": "boolean", "description": "Explicit public sale visibility. Defaults to false; existing purchases are unaffected." }, "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "priceMinor": { "type": "integer", "minimum": 0, "description": "Sale price in minor units (cents); 0 for packs that are only granted" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitKind": { "type": "string", "enum": [ "sessions", "value" ], "description": "sessions (default): one credit pays one appointment. value: units is an amount in minor currency units and a booking debits its displayed price" }, "units": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Credits included: a count of appointments (sessions, at most 1000) or an amount in minor units (value)" }, "validityDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Days after activation before unused credits expire; null never expires" }, "serviceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Services a credit may pay for; empty means every service" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Locations a credit may be used at; empty means every location" }, "active": { "type": "boolean", "description": "Inactive packs stay redeemable but are no longer sold or granted" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "name", "priceMinor", "currency", "units" ], "additionalProperties": false, "description": "A prepaid pack of credits. Removing a pack from the document deactivates it; purchases keep their credits." } }, "reviewRequests": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 0, "maximum": 336, "description": "Hours after the appointment ends before the request is sent" }, "googleReviewUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "The business's Google review link; required to send" }, "cooldownDays": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Minimum days between two requests to the same client" } }, "required": [], "additionalProperties": false, "description": "Automatic review request email after completed appointments. Every eligible client is asked; there is no gating or sentiment filter." }, "policies": { "type": "object", "additionalProperties": true }, "enabledCapabilities": { "type": "array", "items": { "type": "string", "enum": [ "appointments", "payments", "notifications", "calendar_sync", "team", "spaces", "equipment", "packs", "group_sessions", "review_requests" ] }, "description": "Optional modules to switch on: team, spaces, equipment, packs, group_sessions, review_requests. Switching off keeps data. appointments, payments, notifications and calendar_sync are informational and follow their own settings." } }, "required": [ "schemaVersion", "businessTenantId", "locations", "services", "resources", "eligibility", "workingWindows", "closures", "policies", "enabledCapabilities" ], "additionalProperties": false, "description": "Complete configuration-only description of one business tenant." } }, "required": [ "blueprint" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "blueprints:write" ] } }, "/v1/business-tenants/{tenantId}/blueprint/apply": { "post": { "operationId": "applyBlueprintChanges", "summary": "Apply a fresh preview; destructive previews need acknowledgementToken (requires idempotency-key)", "tags": [ "blueprint" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "acknowledgementToken": { "type": "string" } }, "required": [ "previewId" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "blueprints:write" ] } }, "/v1/business-tenants/{tenantId}/blueprint/versions/{version}": { "get": { "operationId": "getBlueprintVersion", "tags": [ "blueprint" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$", "description": "Blueprint version number" } } ], "x-billable": false, "x-permissions-any-of": [ "blueprints:read" ] } }, "/v1/business-tenants/{tenantId}/catalog": { "get": { "operationId": "getPublicCatalog", "summary": "Localized booking catalog: profile, categories, services with media, locations with practical info; ?locale negotiates the language", "tags": [ "catalog" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Language to render, e.g. pt or pt-PT; omitted means the business default", "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/profile": { "get": { "operationId": "getTenantProfile", "summary": "Branding, contact, policies and offered locales", "tags": [ "profile" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] }, "put": { "operationId": "updateTenantProfile", "summary": "Replace branding, contact, policies and locales; colour pairs must reach WCAG AA contrast", "tags": [ "profile" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "logoUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "onPrimaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "backgroundColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "surfaceColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "textColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex colour #rrggbb" }, "bodyFont": { "type": "string", "maxLength": 100 }, "displayFont": { "type": "string", "maxLength": 100 }, "radius": { "type": "integer", "minimum": 0, "maximum": 32 }, "tone": { "type": "string", "enum": [ "formal", "friendly" ] } }, "required": [], "additionalProperties": false, "description": "Visual identity applied to the booking page, emails and client portal. Colour pairs must reach WCAG AA contrast." }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "website": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 } }, "required": [], "additionalProperties": false }, "page": { "type": "object", "properties": { "industry": { "type": "string", "enum": [ "general", "beauty", "barber", "wellness", "health", "fitness", "spaces", "education", "consulting", "crafts", "pets", "auto", "home" ] }, "vocabulary": { "type": "string", "enum": [ "service", "treatment", "consultation", "class", "space", "appointment" ], "description": "The word the business uses for what it sells; falls back to the one implied by industry" }, "serviceLabel": { "type": "string", "maxLength": 60 }, "showCategories": { "type": "boolean" }, "showPacks": { "type": "boolean" }, "packsTitle": { "type": "string", "maxLength": 100 }, "packsDescription": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "tagline": { "type": "string", "maxLength": 200 }, "coverUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "rating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "reviewCount": { "type": [ "integer", "null" ], "minimum": 0 }, "reviewsUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "socialUrl": { "type": [ "string", "null" ], "pattern": "^https?://", "maxLength": 2000 }, "about": { "type": "string", "maxLength": 4000 }, "theme": { "type": "string", "enum": [ "system", "light", "dark" ] } }, "required": [], "additionalProperties": false, "description": "Hosted business page: cover image, tagline and the review score the business displays." }, "policies": { "type": "object", "properties": { "cancellationHours": { "type": "integer", "minimum": 0, "maximum": 720 }, "cancellationText": { "type": "string", "maxLength": 4000 } }, "required": [], "additionalProperties": false }, "locales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "description": "Locales the booking page and emails are offered in; content is translated once and persisted" } }, "required": [], "additionalProperties": false, "description": "Tenant-wide presentation, contact and policy settings." } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/categories": { "get": { "operationId": "listCategories", "tags": [ "categories" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read", "widget:book" ] }, "post": { "operationId": "createCategory", "tags": [ "categories" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/categories/{categoryId}": { "patch": { "operationId": "updateCategory", "tags": [ "categories" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "delete": { "operationId": "deleteCategory", "summary": "Services in the category become uncategorised", "tags": [ "categories" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/media": { "get": { "operationId": "listMedia", "tags": [ "media" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] }, "post": { "operationId": "createMedia", "summary": "Register an image by URL with alt text and focal point", "tags": [ "media" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300 }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "url" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/uploads": { "post": { "operationId": "uploadMedia", "summary": "Upload an image file (PNG, JPEG, WebP, GIF, SVG, AVIF; 4 MB max) as the raw request body; returns its public URL to use as logo, cover or gallery photo. ?variantOf=&width= stores a smaller copy of an image already uploaded, served at its address with -w", "tags": [ "uploads" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "bytes": { "type": "integer" } }, "required": [ "url", "name", "contentType", "bytes" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "variantOf", "in": "query", "required": false, "description": "Name of an image of this business this upload is a resized copy of", "schema": { "type": "string", "maxLength": 500 } }, { "name": "width", "in": "query", "required": false, "description": "Width in pixels of the resized copy (64 to 4000); required with variantOf", "schema": { "type": "string", "pattern": "^[0-9]{2,4}$" } }, { "name": "visibility", "in": "query", "required": false, "description": "private for a customer record photo: served only to a signed-in key that manages this business, never cached publicly (needs customers:write)", "schema": { "type": "string", "enum": [ "public", "private" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "image/*": { "schema": { "type": "string", "contentMediaType": "image/*" } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/media/{assetId}": { "patch": { "operationId": "updateMedia", "tags": [ "media" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300 }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "url" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] }, "delete": { "operationId": "deleteMedia", "tags": [ "media" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/galleries": { "get": { "operationId": "getGallery", "summary": "Read one owner's gallery in order; ownerType and ownerId are required query parameters", "tags": [ "galleries" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ownerType", "in": "query", "required": true, "description": "What the gallery belongs to (tenant, location, service or resource)", "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "ownerId", "in": "query", "required": true, "description": "Id of that owner", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] }, "put": { "operationId": "setGallery", "summary": "Declare an owner's ordered gallery; the first item is primary unless another is flagged", "tags": [ "galleries" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "url": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "altText": { "type": "string", "maxLength": 300, "description": "Alternative text in the tenant's default locale; translated automatically" }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "primary": { "type": "boolean" }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Point kept visible when the image is cropped, as fractions of width and height" } }, "required": [ "id", "url" ], "additionalProperties": false, "description": "An image. Position orders the gallery; exactly one image per owner may be primary." } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "service", "resource", "location", "customer" ] }, "ownerId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "primary": { "type": "boolean" } }, "required": [ "assetId" ], "additionalProperties": false } } }, "required": [ "ownerType", "ownerId", "items" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/translations": { "get": { "operationId": "listTranslations", "summary": "Per field and locale: machine, manual, pending, stale or missing; optional ?locale", "tags": [ "translations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Language to render, e.g. pt or pt-PT; omitted means the business default", "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:read" ] }, "put": { "operationId": "overrideTranslation", "summary": "Manual translation kept across later source edits", "tags": [ "translations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "service", "category", "resource", "location", "media", "profile" ] }, "entityId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "field": { "type": "string", "minLength": 1, "maxLength": 60 }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "entityType", "entityId", "field", "locale", "text" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/translations/reset": { "post": { "operationId": "resetTranslation", "summary": "Drop a translation and ask the provider again", "tags": [ "translations" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "service", "category", "resource", "location", "media", "profile" ] }, "entityId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "field": { "type": "string", "minLength": 1, "maxLength": 60 }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } }, "required": [ "entityType", "entityId", "field", "locale" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/billing": { "get": { "operationId": "getBilling", "summary": "Sutempo subscription of this business: plan, status, trial (active, end, still available), billed locations, sellable plans and their Stripe prices", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "billing:read" ] } }, "/v1/business-tenants/{tenantId}/billing/trial": { "post": { "operationId": "startBillingTrial", "summary": "Start the 14-day Pro trial, once per business; refused when it was already used or when the business ever had a subscription", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/checkout": { "post": { "operationId": "startBillingCheckout", "summary": "Stripe Checkout in subscription mode for a sellable plan (Pro); without a card while the Pro trial runs, the subscription starts at its end; otherwise billed at once", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "etablissement", "membership" ] }, "immediate": { "type": "boolean" } }, "required": [ "plan" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/portal": { "post": { "operationId": "openBillingPortal", "summary": "One-time link to the Stripe customer portal (card, invoices, cancellation)", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/plan": { "post": { "operationId": "changeBillingPlan", "summary": "Move the running subscription between plans: an upgrade to a sellable plan is invoiced and charged at once, a downgrade is scheduled for the end of the paid period; Scale cannot be joined", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "etablissement", "membership" ] } }, "required": [ "plan" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/plan/preview": { "post": { "operationId": "previewBillingPlanChange", "summary": "Ce qui sera facturé aujourd'hui, ou la date de bascule, avant de confirmer un changement d'offre", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "etablissement", "membership" ] } }, "required": [ "plan" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/plan/scheduled/cancel": { "post": { "operationId": "cancelScheduledBillingPlanChange", "summary": "Annuler une descente d'offre planifiée ; l'offre en cours reste en place", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/business-tenants/{tenantId}/billing/resync": { "post": { "operationId": "resyncBilling", "summary": "Relire l'abonnement chez Stripe et reposer l'etat local dessus; filet du webhook", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "billing:write" ] } }, "/v1/billing/webhook": { "post": { "operationId": "receiveBillingWebhook", "summary": "Stripe Billing callback; authenticated by the provider signature, replay-safe", "tags": [ "billing" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "x-billable": false, "x-access": "provider-webhook" } }, "/v1/business-tenants/{tenantId}/stripe-connect": { "get": { "operationId": "getStripeConnect", "tags": [ "stripe-connect" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "payments:read" ] }, "post": { "operationId": "startStripeConnect", "tags": [ "stripe-connect" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "payments:write" ] } }, "/v1/business-tenants/{tenantId}/payment-settings": { "get": { "operationId": "getPaymentSettings", "tags": [ "payment-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "payments:read" ] }, "put": { "operationId": "updatePaymentSettings", "summary": "Turn payment or deposit collection on for the connected business account", "tags": [ "payment-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "full", "deposit_percent", "deposit_fixed" ] }, "depositPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "depositFixedMinor": { "type": "integer", "minimum": 0 }, "holdMinutes": { "type": "integer", "minimum": 30, "maximum": 1440, "description": "How long a slot stays held while the client pays" }, "refundOnCancellation": { "type": "string", "enum": [ "always", "outside_window", "never" ] } }, "required": [], "additionalProperties": false, "description": "Payment or deposit collected at booking. Provider credentials are platform configuration, never tenant data." } } } }, "x-billable": false, "x-permissions-any-of": [ "payments:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/payment": { "post": { "operationId": "createAppointmentPayment", "summary": "Start (or resume) the provider checkout for a held appointment that requires payment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "successUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "cancelUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } }, "required": [ "successUrl", "cancelUrl" ], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "bookings:write", "widget:book" ] }, "get": { "operationId": "getAppointmentPayment", "summary": "Payment state and a public summary of the appointment it secures", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:read", "widget:book", "payments:read" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/payment/mark-paid": { "post": { "operationId": "markAppointmentPaymentPaid", "summary": "Record that an appointment payable on site was paid at the business; no provider payment, no automatic refund", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "payments:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/payment/refund": { "post": { "operationId": "refundAppointmentPayment", "summary": "Queue a refund of the remaining paid amount", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "payments:write" ] } }, "/v1/payments/webhooks/{provider}": { "post": { "operationId": "receivePaymentWebhook", "summary": "Provider callback; authenticated by the provider signature, replay-safe", "tags": [ "payments" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "stripe" ], "description": "Payment provider" } } ], "x-billable": false, "x-access": "provider-webhook" } }, "/v1/business-tenants/{tenantId}/notification-settings": { "get": { "operationId": "getNotificationSettings", "tags": [ "notification-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "notifications:read" ] }, "put": { "operationId": "updateNotificationSettings", "tags": [ "notification-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "replyToEmail": { "type": [ "string", "null" ], "maxLength": 320 }, "senderName": { "type": [ "string", "null" ], "maxLength": 120 }, "reminderHoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 }, "reminderEnabled": { "type": "boolean", "description": "Send the reminder before the appointment; defaults to true" }, "logoUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "Email-only logo override (https); null inherits the profile" }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Email-only button colour override; null inherits the profile" }, "signature": { "type": "string", "maxLength": 600, "description": "Closing plain text under the sign-off" }, "texts": { "type": "object", "properties": { "confirmation": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "reminder": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rescheduled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "cancelled": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "instructions": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "thank_you": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "rebook": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "review": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_received": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_declined": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "request_expired": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" }, "pack_receipt": { "type": "string", "maxLength": 1000, "description": "Plain text; {name} {tenant} {service} {date} {time} {location} {resource} are replaced" } }, "required": [], "additionalProperties": false, "description": "Intro text per email; empty means the localized default" }, "instructions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursBefore": { "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Practical instructions before the appointment" }, "thankYou": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hoursAfter": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": [], "additionalProperties": false, "description": "Thank-you note after the appointment" }, "rebook": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysAfter": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [], "additionalProperties": false, "description": "Invitation to book again; sent only to clients whose marketing state is subscribed at send time" } }, "required": [], "additionalProperties": false, "description": "Automatic emails sent by the platform on behalf of the business. The From address is platform configuration; the business sets the sender name and Reply-To." } } } }, "x-billable": false, "x-permissions-any-of": [ "notifications:write" ] } }, "/v1/business-tenants/{tenantId}/notifications": { "get": { "operationId": "listNotifications", "summary": "Email deliveries with status and last error; optional ?appointmentId", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "query", "required": false, "description": "Only the notifications of this appointment", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "notifications:read" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections": { "get": { "operationId": "listCalendarConnections", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "calendar:read" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections/google/authorize": { "post": { "operationId": "authorizeGoogleCalendar", "summary": "Returns the consent URL for one person's calendar; the redirect completes the connection", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "redirectUri": { "type": "string", "pattern": "^https?://", "maxLength": 2000 } }, "required": [ "resourceId", "redirectUri" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "calendar:write" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections/{connectionId}/calendars": { "get": { "operationId": "listGoogleCalendars", "summary": "The calendars of the connected Google account, each marked with the import rules already chosen for it", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "calendar:read" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections/{connectionId}/calendars/{calendarId}": { "put": { "operationId": "updateTrackedCalendar", "summary": "Import a calendar or stop importing it, and set what its events do: block availability, appear in the agenda, hide their titles, cover the whole day", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "calendarId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Google calendar id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tracked": { "type": "boolean" }, "summary": { "type": "string" }, "blocksAvailability": { "type": "boolean" }, "visibleInAgenda": { "type": "boolean" }, "hideTitles": { "type": "boolean" }, "allDayBlocks": { "type": "boolean" } }, "required": [ "tracked" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "calendar:write" ] } }, "/v1/business-tenants/{tenantId}/calendar-events": { "get": { "operationId": "listImportedCalendarEvents", "summary": "Events imported from the connected calendars between ?from and ?to, for display only; titles are omitted where the merchant chose to share busy time alone", "tags": [ "calendar-events" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the range; now by default", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "End of the range; 31 days after from by default", "schema": { "type": "string", "format": "date-time" } } ], "x-billable": false, "x-permissions-any-of": [ "calendar:read" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections/{connectionId}/disconnect": { "post": { "operationId": "disconnectCalendar", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "calendar:write" ] } }, "/v1/business-tenants/{tenantId}/calendar-connections/{connectionId}/sync": { "post": { "operationId": "syncCalendar", "tags": [ "calendar-connections" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "calendar:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/access-link": { "post": { "operationId": "createAccessLink", "summary": "Mint a self-service link for the client (returned once)", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/access-link/revoke": { "post": { "operationId": "revokeAccessLinks", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "bookings:write" ] } }, "/v1/business-tenants/{tenantId}/page": { "get": { "operationId": "getBusinessPage", "summary": "The hosted business page in one call: localized catalog, opening hours, review score and the public booking key; 404 until the business enables its page; ?locale negotiates the language", "tags": [ "page" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Language to render, e.g. pt or pt-PT; omitted means the business default", "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } }, { "name": "preview", "in": "query", "required": false, "description": "1 with the owner's credential shows the page before it is published", "schema": { "type": "string", "enum": [ "1" ] } } ], "x-billable": false, "x-access": "public" } }, "/v1/business-tenants/{tenantId}/address-suggestions": { "get": { "operationId": "suggestAddresses", "summary": "Address completion for ?q, answered from OpenStreetMap through Photon. Free, keyless, proxied here because the admin's connect-src is 'self'. Returns at most five entries; an empty list simply means: type the address by hand.", "tags": [ "address-suggestions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "line1": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "label", "line1", "postalCode", "city", "region", "countryCode" ], "additionalProperties": false } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text address to complete", "schema": { "type": "string", "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/page/slug-check": { "get": { "operationId": "checkPublicSlug", "summary": "Is ?slug free for this business? Answers {slug, available, reason} with reason in format|length|reserved|taken", "tags": [ "page" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "slug", "available", "reason" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "slug", "in": "query", "required": true, "description": "Candidate public address, e.g. atelier-lumiere", "schema": { "type": "string", "maxLength": 80 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/business-tenants/{tenantId}/page/enable": { "post": { "operationId": "enableBusinessPage", "summary": "Publish the hosted business page at / (or /b?tenant= while no slug is set): mints the public booking key it uses (idempotent, a second call rotates the key)", "tags": [ "page" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "catalog:write" ] } }, "/v1/self-service/pack-purchases": { "post": { "operationId": "createAccountPackPurchase", "summary": "Buy a published pack for the authenticated customer", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "productId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "requestId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [ "tenantId", "productId", "requestId" ], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/bookings/hold": { "post": { "operationId": "holdAccountBooking", "summary": "Hold a booking for the authenticated customer and optionally apply their credits", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "startsAt": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer", "minimum": 1 }, "sessionId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "purchaseId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "requestId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locale": { "type": "string" }, "phone": { "type": "string", "maxLength": 40 }, "notes": { "type": "string", "maxLength": 4000 } }, "required": [ "tenantId", "locationId", "serviceId", "resourceId", "startsAt", "requestId" ], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/account": { "get": { "operationId": "getSelfServiceAccount", "summary": "Every booking of the signed-in person at this business, with the business profile; the portal sends `session` in x-customer-access-token and the server reads the Sutempo session cookie", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "Language to render, e.g. pt or pt-PT; omitted means the business default", "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } } ], "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/appointment": { "get": { "operationId": "getSelfServiceAppointment", "summary": "The client’s appointment, practical information and policy; the management link from the confirmation email goes in x-customer-access-token, and a portal session names the appointment with ?appointment=", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/availability": { "get": { "operationId": "getSelfServiceAvailability", "summary": "Slots the client may move to on ?localDate, across eligible people", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "localDate", "in": "query", "required": true, "description": "Local date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" } }, { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/reschedule": { "post": { "operationId": "rescheduleSelfServiceAppointment", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [ "startsAt" ], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/cancel": { "post": { "operationId": "cancelSelfServiceAppointment", "summary": "Cancel from the client portal; a reason is required when the business asks for one", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellationReason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } }, "/v1/business-tenants/{tenantId}/modules": { "get": { "operationId": "listTenantModules", "summary": "Optional modules with their state for this business and whether the category preset recommends them", "tags": [ "modules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "modules:read", "blueprints:read" ] } }, "/v1/business-tenants/{tenantId}/modules/{moduleId}": { "put": { "operationId": "setTenantModule", "summary": "Switch an optional module on or off; never deletes module data", "tags": [ "modules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "moduleId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Module id, as listed by listTenantModules" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "modules:write", "blueprints:write" ] } }, "/v1/business-tenants/{tenantId}/pack-products": { "get": { "operationId": "listPackProducts", "tags": [ "pack-products" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "packs:read", "widget:book" ] }, "post": { "operationId": "createPackProduct", "summary": "A sellable or grantable pack of credits; empty serviceIds/locationIds mean any", "tags": [ "pack-products" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean", "description": "Explicit public sale visibility. Defaults to false; existing purchases are unaffected." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "priceMinor": { "type": "integer", "minimum": 0, "description": "Sale price in minor units (cents); 0 for packs that are only granted" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitKind": { "type": "string", "enum": [ "sessions", "value" ], "description": "sessions (default): one credit pays one appointment. value: units is an amount in minor currency units and a booking debits its displayed price" }, "units": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Credits included: a count of appointments (sessions, at most 1000) or an amount in minor units (value)" }, "validityDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Days after activation before unused credits expire; null never expires" }, "serviceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Services a credit may pay for; empty means every service" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Locations a credit may be used at; empty means every location" }, "active": { "type": "boolean", "description": "Inactive packs stay redeemable but are no longer sold or granted" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "name", "priceMinor", "currency", "units" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "packs:write" ] } }, "/v1/business-tenants/{tenantId}/pack-products/{productId}": { "patch": { "operationId": "updatePackProduct", "tags": [ "pack-products" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean", "description": "Explicit public sale visibility. Defaults to false; existing purchases are unaffected." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "priceMinor": { "type": "integer", "minimum": 0, "description": "Sale price in minor units (cents); 0 for packs that are only granted" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitKind": { "type": "string", "enum": [ "sessions", "value" ], "description": "sessions (default): one credit pays one appointment. value: units is an amount in minor currency units and a booking debits its displayed price" }, "units": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Credits included: a count of appointments (sessions, at most 1000) or an amount in minor units (value)" }, "validityDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Days after activation before unused credits expire; null never expires" }, "serviceIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Services a credit may pay for; empty means every service" }, "locationIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "UUID" }, "description": "Locations a credit may be used at; empty means every location" }, "active": { "type": "boolean", "description": "Inactive packs stay redeemable but are no longer sold or granted" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "name", "priceMinor", "currency", "units" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "packs:write" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases": { "get": { "operationId": "listPackPurchases", "summary": "Purchases with their live balance; optional ?customerId", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only the purchases of this client", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "packs:read" ] }, "post": { "operationId": "createPackPurchase", "summary": "grant issues credits at once (merchant); sale creates a purchase awaiting payment, cashed at the counter or through the checkout (requires the packs module)", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "customerId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "mode": { "type": "string", "enum": [ "grant", "sale" ] }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "productId", "customerId", "mode" ], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "packs:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}": { "get": { "operationId": "getPackPurchase", "summary": "The purchase and its complete credit ledger", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "packs:read" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/activate": { "post": { "operationId": "activatePackPurchase", "summary": "Confirm an offline payment: credits become usable; optional paymentMethod is kept on the ledger", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "cash", "card_on_site", "transfer", "other" ] } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "packs:write" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/cancel": { "post": { "operationId": "cancelPackPurchase", "summary": "Closes the pack; remaining credits are written off in the ledger", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 200 } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "packs:write" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/adjust": { "post": { "operationId": "adjustPackPurchase", "summary": "Manual credit correction (positive or negative); the balance never goes below zero", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "units": { "type": "integer", "minimum": -100000000, "maximum": 100000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "units", "reason" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "packs:write" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/checkout": { "post": { "operationId": "createPackPurchaseCheckout", "summary": "Start (or resume) the provider checkout for a pending pack sale", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "successUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "cancelUrl": { "type": "string", "pattern": "^https?://", "maxLength": 2000 }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" } }, "required": [ "successUrl", "cancelUrl" ], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "packs:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/payment": { "get": { "operationId": "getPackPurchasePayment", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "packs:read", "widget:book", "payments:read" ] } }, "/v1/business-tenants/{tenantId}/pack-purchases/{purchaseId}/payment/refund": { "post": { "operationId": "refundPackPurchasePayment", "summary": "Queue a refund of the pack payment; the purchase closes when the provider confirms", "tags": [ "pack-purchases" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-billable": false, "x-permissions-any-of": [ "payments:write" ] } }, "/v1/business-tenants/{tenantId}/appointments/{appointmentId}/redeem-credit": { "post": { "operationId": "redeemAppointmentCredit", "summary": "Pay a held or confirmed appointment with one eligible credit of its customer; waives the pending payment", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "packs:write", "bookings:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/group-sessions": { "get": { "operationId": "listGroupSessions", "summary": "Scheduled sessions starting in [from, to) (default: next 30 days) with seat counts; optional ?serviceId ?locationId ?includeCancelled", "tags": [ "group-sessions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the range; now by default", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "End of the range; 30 days after from by default, at most 92", "schema": { "type": "string", "format": "date-time" } }, { "name": "serviceId", "in": "query", "required": false, "description": "Only this service", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "includeCancelled", "in": "query", "required": false, "description": "true also lists cancelled sessions", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "x-billable": false, "x-permissions-any-of": [ "sessions:read", "widget:book", "bookings:read" ] }, "post": { "operationId": "scheduleGroupSessions", "summary": "Schedule a session (or a weekly series) at a local time in the location's timezone; returns every created session", "tags": [ "group-sessions" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locationId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "resourceId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "localDate": { "type": "string", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$", "description": "Local calendar date YYYY-MM-DD" }, "startLocal": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Local wall time HH:mm" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 500 }, "title": { "type": "string", "maxLength": 200 }, "repeatWeeks": { "type": "integer", "minimum": 1, "maximum": 52, "description": "Number of weekly occurrences starting on localDate" } }, "required": [ "serviceId", "locationId", "resourceId", "localDate", "startLocal", "capacity" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "sessions:write" ] } }, "/v1/business-tenants/{tenantId}/group-sessions/{sessionId}": { "get": { "operationId": "getGroupSession", "tags": [ "group-sessions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "sessions:read", "widget:book", "bookings:read" ] } }, "/v1/business-tenants/{tenantId}/group-sessions/{sessionId}/cancel": { "post": { "operationId": "cancelGroupSession", "summary": "Cancel a session; refused (409) while it has seats unless cancelSeats is true, which cancels every seat first", "tags": [ "group-sessions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelSeats": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "sessions:write" ] } }, "/v1/business-tenants/{tenantId}/group-sessions/{sessionId}/seats": { "post": { "operationId": "holdGroupSessionSeat", "summary": "Hold one seat as a regular appointment; confirm it through the appointment API", "tags": [ "group-sessions" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "locale": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "captchaToken": { "type": "string", "maxLength": 2048 } }, "required": [], "additionalProperties": false } } } }, "x-billable": true, "x-permissions-any-of": [ "bookings:write", "widget:book" ] } }, "/v1/business-tenants/{tenantId}/review-request-settings": { "get": { "operationId": "getReviewRequestSettings", "tags": [ "review-request-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-billable": false, "x-permissions-any-of": [ "reviews:read" ] }, "put": { "operationId": "updateReviewRequestSettings", "summary": "Delay after the appointment, Google review link and cooldown; every eligible client is asked, no gating", "tags": [ "review-request-settings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 0, "maximum": 336, "description": "Hours after the appointment ends before the request is sent" }, "googleReviewUrl": { "type": [ "string", "null" ], "pattern": "^https://", "maxLength": 2000, "description": "The business's Google review link; required to send" }, "cooldownDays": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Minimum days between two requests to the same client" } }, "required": [], "additionalProperties": false, "description": "Automatic review request email after completed appointments. Every eligible client is asked; there is no gating or sentiment filter." } } } }, "x-billable": false, "x-permissions-any-of": [ "reviews:write" ] } }, "/v1/business-tenants/{tenantId}/review-requests": { "get": { "operationId": "listReviewRequests", "summary": "Review requests with status and reason; optional ?appointmentId ?customerId", "tags": [ "review-requests" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appointmentId", "in": "query", "required": false, "description": "Only the requests of this appointment", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only the requests of this client", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-permissions-any-of": [ "reviews:read" ] } }, "/v1/business-tenants/{tenantId}/customers/{customerId}/review-opt-out": { "put": { "operationId": "setReviewOptOut", "summary": "Record that a client does (or no longer) want review requests", "tags": [ "customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID); retrying with the same key and body returns the first result", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optedOut": { "type": "boolean" } }, "required": [ "optedOut" ], "additionalProperties": false } } } }, "x-billable": false, "x-permissions-any-of": [ "reviews:write" ] } }, "/v1/self-service/modules": { "get": { "operationId": "getSelfServiceModules", "summary": "Module state for this client: usable credits, whether this appointment is covered by one, review request preference", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/redeem-credit": { "post": { "operationId": "redeemSelfServiceCredit", "summary": "Pay this appointment with one of the client's credits", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "required": [], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } }, "/v1/self-service/review-opt-out": { "post": { "operationId": "setSelfServiceReviewOptOut", "tags": [ "self-service" ], "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "name": "appointment", "in": "query", "required": false, "description": "Account session only: the appointment this call is about; a signed link already names it", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optedOut": { "type": "boolean" } }, "required": [ "optedOut" ], "additionalProperties": false } } } }, "x-billable": false, "x-access": "customer-token" } } } }