{ "openapi": "3.0.3", "info": { "title": "Healthlink public discovery and authorized booking", "version": "1.0.0", "description": "Five HLD clinics, plus a Fresha destination for Biggera Waters. Customer sign-in and explicit approval in Quick authorize one exact quote for five minutes. A phone number or caller-provided confirmation boolean is insufficient. Existing ordinary Quick guest booking is unchanged. No new payment operations. Unverified durations, complex packages and conditional discount offers require clinic confirmation." }, "servers": [ { "url": "https://quick.healthlinkpro.com/massage-booking/agent/v1" } ], "paths": { "/clinics": { "get": { "operationId": "listClinics", "summary": "List approved clinics and external booking destinations", "parameters": [], "responses": { "200": { "description": "Success. Never evidence of a held or confirmed appointment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clinics": { "type": "array", "items": { "$ref": "#/components/schemas/Clinic" } }, "retrievedAt": { "type": "string" } }, "required": [ "clinics", "retrievedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid selection or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Outside the approved public booking catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable or feature disabled; do not interpret as no available times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit. Wait and retry with backoff; existing gateway error envelope may differ." } } } }, "/services": { "get": { "operationId": "listServices", "summary": "List the current HLD public services for one approved clinic", "parameters": [ { "name": "clinicId", "in": "query", "required": true, "description": "", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success. Never evidence of a held or confirmed appointment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clinicId": { "type": "integer", "format": "int64" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "retrievedAt": { "type": "string" } }, "required": [ "clinicId", "services", "retrievedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid selection or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Outside the approved public booking catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable or feature disabled; do not interpret as no available times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit. Wait and retry with backoff; existing gateway error envelope may differ." } } } }, "/catalog": { "get": { "operationId": "getCatalog", "summary": "Get a consistent public directory snapshot, without appointment inventory", "parameters": [], "responses": { "200": { "description": "Success. Never evidence of a held or confirmed appointment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "format": "int64" }, "clinics": { "type": "array", "items": { "$ref": "#/components/schemas/Clinic" } }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "capabilities": { "type": "object", "properties": { "catalog": { "type": "boolean" }, "availability": { "type": "boolean" }, "onlinePayment": { "type": "boolean" } }, "required": [ "catalog", "availability", "onlinePayment" ], "additionalProperties": false }, "factsVersion": { "type": "string" }, "generatedAt": { "type": "string" } }, "required": [ "schemaVersion", "clinics", "services", "capabilities", "factsVersion", "generatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid selection or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Outside the approved public booking catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable or feature disabled; do not interpret as no available times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit. Wait and retry with backoff; existing gateway error envelope may differ." } } } }, "/availability": { "get": { "operationId": "findAvailableTimes", "summary": "Check 1\u20137 dates in Brisbane local time; results are not held", "parameters": [ { "name": "clinicId", "in": "query", "required": true, "description": "", "schema": { "type": "integer", "format": "int64" } }, { "name": "serviceId", "in": "query", "required": true, "description": "", "schema": { "type": "integer", "format": "int64" } }, { "name": "fromDate", "in": "query", "required": true, "description": "", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "required": false, "description": "Inclusive; defaults to fromDate. No dates beyond today + 90 days.", "schema": { "type": "string", "format": "date" } }, { "name": "localTimeFrom", "in": "query", "required": false, "description": "Earliest local start, HH:mm.", "schema": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$" } }, { "name": "localTimeTo", "in": "query", "required": false, "description": "Latest local start, HH:mm.", "schema": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, { "name": "therapistId", "in": "query", "required": false, "description": "Only when the customer requested a specific therapist; otherwise omit.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success. Never evidence of a held or confirmed appointment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Invalid selection or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Outside the approved public booking catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable or feature disabled; do not interpret as no available times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit. Wait and retry with backoff; existing gateway error envelope may differ." } } } }, "/quotes": { "post": { "operationId": "quoteBooking", "summary": "Check an exact choice and current price; no booking, SMS, hold or payment", "parameters": [], "responses": { "200": { "description": "Inspect the returned booking and payment states separately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in required for a first-party confirmation step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing/expired one-request capability or customer authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Selection changed, slot unavailable, clinic confirmation required, request declined, or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request or quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least Retry-After before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure. Read the request status before retrying a booking with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Selection" } } } } } }, "/booking-requests": { "post": { "operationId": "prepareBooking", "summary": "Prepare a 15-minute customer review context; does not create an appointment", "parameters": [], "responses": { "200": { "description": "Inspect the returned booking and payment states separately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedRequest" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in required for a first-party confirmation step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing/expired one-request capability or customer authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Selection changed, slot unavailable, clinic confirmation required, request declined, or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request or quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least Retry-After before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure. Read the request status before retrying a booking with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Selection" } } } } } }, "/booking-request": { "get": { "operationId": "getBookingRequest", "summary": "Recover only this request or its booking state; poll at most once every five seconds", "parameters": [ { "name": "requestId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Inspect the returned booking and payment states separately.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RequestStatus" }, { "$ref": "#/components/schemas/Receipt" } ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in required for a first-party confirmation step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing/expired one-request capability or customer authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Selection changed, slot unavailable, clinic confirmation required, request declined, or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request or quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least Retry-After before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure. Read the request status before retrying a booking with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "RequestCapability": [] } ] } }, "/bookings": { "post": { "operationId": "confirmBooking", "summary": "Create only the exact customer-authorized booking; reuse one idempotency key on retries", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{16,100}$" }, "description": "Use bookingIdempotencyKey from the prepared request. Same key returns the original booking; a different key for the same request is rejected." } ], "responses": { "200": { "description": "Inspect the returned booking and payment states separately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in required for a first-party confirmation step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing/expired one-request capability or customer authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Selection changed, slot unavailable, clinic confirmation required, request declined, or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request or quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least Retry-After before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure. Read the request status before retrying a booking with the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" } }, "required": [ "requestId" ], "additionalProperties": false } } } }, "security": [ { "RequestCapability": [] } ] } } }, "components": { "schemas": { "Clinic": { "type": "object", "properties": { "slug": { "type": "string" }, "area": { "type": "string" }, "publicName": { "type": "string" }, "address": { "type": "string" }, "phoneDisplay": { "type": "string" }, "phoneE164": { "type": "string" }, "mapsUrl": { "type": "string" }, "hoursSource": { "type": "string" }, "hoursObservedOn": { "type": "string" }, "bookingUrl": { "type": "string" }, "clinicUrl": { "type": "string" }, "brandRelationship": { "type": "string" }, "addressSource": { "type": "string" }, "verifiedOn": { "type": "string" }, "clinicId": { "type": "integer", "format": "int64", "nullable": true }, "timeZone": { "type": "string", "enum": [ "Australia/Brisbane" ] }, "regularHours": { "type": "object", "properties": { "Mon": { "type": "string" }, "Tue": { "type": "string" }, "Wed": { "type": "string" }, "Thu": { "type": "string" }, "Fri": { "type": "string" }, "Sat": { "type": "string" }, "Sun": { "type": "string" } }, "required": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ], "additionalProperties": false }, "specialHoursConfirmed": { "type": "boolean" }, "bookingProvider": { "type": "string", "enum": [ "HLD", "Fresha" ] }, "availabilityMode": { "type": "string", "enum": [ "live_hld", "external_booking_provider" ] } }, "required": [ "slug", "area", "publicName", "address", "phoneDisplay", "phoneE164", "mapsUrl", "hoursSource", "hoursObservedOn", "bookingUrl", "clinicUrl", "brandRelationship", "addressSource", "verifiedOn", "clinicId", "timeZone", "regularHours", "specialHoursConfirmed", "bookingProvider", "availabilityMode" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "serviceId": { "type": "integer", "format": "int64" }, "clinicId": { "type": "integer", "format": "int64" }, "categoryId": { "type": "integer", "format": "int64" }, "categoryName": { "type": "string" }, "name": { "type": "string" }, "durationStatus": { "type": "string" }, "priceType": { "type": "string" }, "bookingUrl": { "type": "string" }, "customerDurationMinutes": { "type": "integer", "format": "int64", "nullable": true }, "currency": { "type": "string", "enum": [ "AUD" ] }, "priceMinor": { "type": "integer", "format": "int64", "nullable": true }, "healthFundMayApply": { "type": "boolean", "description": "HLD service eligibility flag only. Individual rebates depend on the customer's extras cover, waiting periods, remaining limits, treatment and therapist recognition with their fund. See https://www.healthlinkmassage.com/services/health-fund-rebates/ for major funds and claiming guidance. This flag does not guarantee a claim or validate fund-specific therapist eligibility." }, "requiresConsent": { "type": "boolean" }, "consentTerms": { "type": "string", "nullable": true }, "requiresOperatorConfirmation": { "type": "boolean" } }, "required": [ "serviceId", "clinicId", "categoryId", "categoryName", "name", "durationStatus", "priceType", "bookingUrl", "customerDurationMinutes", "currency", "priceMinor", "healthFundMayApply", "requiresConsent", "consentTerms", "requiresOperatorConfirmation" ], "additionalProperties": false }, "Slot": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" }, "customerDurationMinutes": { "type": "integer", "format": "int64", "nullable": true }, "serviceEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "bookingFlow": { "type": "string", "enum": [ "TREATMENT_FIRST", "THERAPIST_FIRST" ] }, "therapistId": { "type": "integer", "format": "int64", "nullable": true }, "bookingUrl": { "type": "string" } }, "required": [ "startsAt", "timeZone", "customerDurationMinutes", "serviceEndsAt", "bookingFlow", "therapistId", "bookingUrl" ], "additionalProperties": false }, "Availability": { "type": "object", "properties": { "clinicId": { "type": "integer", "format": "int64" }, "serviceId": { "type": "integer", "format": "int64" }, "timeZone": { "type": "string" }, "retrievedAt": { "type": "string", "format": "date-time" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/Slot" } }, "truncated": { "type": "boolean" }, "inventoryHeld": { "type": "boolean" }, "price": { "type": "object", "properties": { "currency": { "type": "string" }, "amountMinor": { "type": "integer", "format": "int64", "nullable": true }, "type": { "type": "string" } }, "required": [ "currency", "amountMinor", "type" ], "additionalProperties": false }, "requiresOperatorConfirmation": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "clinicId", "serviceId", "timeZone", "retrievedAt", "fromDate", "toDate", "slots", "truncated", "inventoryHeld", "price", "requiresOperatorConfirmation", "message" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Selection": { "type": "object", "properties": { "clinicId": { "type": "integer", "format": "int64" }, "serviceId": { "type": "integer", "format": "int64" }, "startsAt": { "type": "string", "format": "date-time" }, "therapistId": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "clinicId", "serviceId", "startsAt" ], "additionalProperties": false }, "QuoteSummary": { "type": "object", "properties": { "selection": { "$ref": "#/components/schemas/Selection" }, "clinicName": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "serviceName": { "type": "string" }, "serviceConditions": { "type": "string" }, "currency": { "type": "string" }, "bookingFlow": { "type": "string" }, "paymentMode": { "type": "string" }, "paymentMessage": { "type": "string" }, "policyVersion": { "type": "string" }, "termsUrl": { "type": "string" }, "privacyUrl": { "type": "string" }, "customerDurationMinutes": { "type": "integer", "format": "int64" }, "amountMinor": { "type": "integer", "format": "int64" }, "requiresConsent": { "type": "boolean" }, "consentTerms": { "type": "string", "nullable": true }, "onlinePayment": { "type": "boolean" }, "therapistName": { "type": "string", "nullable": true } }, "required": [ "selection", "clinicName", "address", "phone", "serviceName", "serviceConditions", "currency", "bookingFlow", "paymentMode", "paymentMessage", "policyVersion", "termsUrl", "privacyUrl", "customerDurationMinutes", "amountMinor", "requiresConsent", "consentTerms", "onlinePayment", "therapistName" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "selection": { "$ref": "#/components/schemas/Selection" }, "summary": { "$ref": "#/components/schemas/QuoteSummary" }, "quoteVersion": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "inventoryHeld": { "type": "boolean" }, "onlinePayment": { "type": "boolean" }, "nextAction": { "type": "string" } }, "required": [ "selection", "summary", "quoteVersion", "expiresAt", "inventoryHeld", "onlinePayment", "nextAction" ], "additionalProperties": false }, "PreparedRequest": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "requestToken": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Private one-request capability. Never place in URLs or logs. Valid for result retrieval for 24 hours." }, "quote": { "$ref": "#/components/schemas/Quote" }, "bookingIdempotencyKey": { "type": "string" }, "confirmationUrl": { "type": "string", "format": "uri", "description": "One-use customer handoff. Give to the customer; do not crawl or pre-open it." }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "requestId", "requestToken", "quote", "bookingIdempotencyKey", "confirmationUrl", "status", "message" ], "additionalProperties": false }, "RequestStatus": { "type": "object", "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_confirmation", "authorized", "authorization_expired", "expired", "rejected" ] }, "quote": { "$ref": "#/components/schemas/Quote" }, "bookingIdempotencyKey": { "type": "string" } }, "required": [ "requestId", "status", "quote", "bookingIdempotencyKey" ], "additionalProperties": false }, "Receipt": { "type": "object", "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed" ] }, "bookingId": { "type": "integer", "format": "int64" }, "bookingStatus": { "type": "string", "enum": [ "confirmed", "cancelled", "in_progress", "completed", "unknown" ] }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "partially_refunded", "refunded", "failed", "unknown" ] }, "onlinePayment": { "type": "boolean" }, "selection": { "$ref": "#/components/schemas/Selection" }, "summary": { "$ref": "#/components/schemas/QuoteSummary" }, "confirmedAt": { "type": "string", "format": "date-time" }, "retrievedAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" } }, "required": [ "requestId", "status", "bookingId", "bookingStatus", "paymentStatus", "onlinePayment", "selection", "summary", "confirmedAt", "message" ], "additionalProperties": false } }, "securitySchemes": { "RequestCapability": { "type": "apiKey", "in": "header", "name": "X-Booking-Request-Token", "description": "Short-lived capability for one booking request, returned by prepare. Only customer approval in Quick authorizes creation. It is not an account login and gives no history access." } } }, "externalDocs": { "description": "MCP Streamable HTTP endpoint, supporting protocol 2025-11-25 and 2025-06-18", "url": "https://quick.healthlinkpro.com/massage-booking/agent/v1/mcp" } }