{ "openapi": "3.1.0", "x-comment": "GENERATED from supabase/functions/_shared/agent-booking-contract.ts. Do not edit by hand: npm run agent-docs.", "info": { "title": "Enhanced Intelligence LLC: booking for AI agents", "version": "1.0.0", "description": "Book a business that runs on Cortex, machine to machine and with no key. Read the business card, ask for open times (optionally narrowed to the customer's own free windows), and book. A business either confirms a booking at once or receives it as a request its owner approves; the answer says which. The business sees that an agent made the booking, and which one. There is an MCP server at /mcp with the same tools. Limits: 60 reads a minute and 10 bookings an hour per network address, 30 bookings a day per business. Only open times are ever shown: never another customer, a job, a block or a reason a time is not open." }, "servers": [ { "url": "https://book.enhancedint.com/enhanced-intelligence", "description": "Enhanced Intelligence LLC, on Cortex." } ], "paths": { "/agent": { "get": { "operationId": "getBusiness", "security": [], "summary": "The business card", "description": "What the business offers, what a booking needs, how a booking is confirmed, the limits and the other addresses. Call it first.", "responses": { "200": { "description": "The card.", "content": { "application/json": { "schema": { "type": "object", "description": "The business card: what the business offers, what a booking needs, how a booking is confirmed, the limits and where everything is.", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "industry": { "type": "string" }, "bookable": { "type": "boolean", "description": "False when the door does not serve this business's kind of booking yet; the human page still works." }, "unavailableReason": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mobile", "shop", "online" ] }, "address": { "type": [ "string", "null" ] }, "serviceArea": { "type": [ "string", "null" ] }, "meeting": { "type": [ "string", "null" ] } } }, "timezone": { "type": [ "string", "null" ] }, "hours": { "type": [ "object", "null" ], "description": "Weekly hours by weekday (mon..sun): {open, close} in the business's zone, or null for a closed day." }, "services": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "priceNote": { "type": [ "string", "null" ] }, "durationMinutes": { "type": [ "integer", "null" ] }, "kind": { "type": "string", "enum": [ "package", "add_on", "meeting" ] } }, "required": [ "slug", "name", "kind" ] } }, "booking": { "type": "object", "properties": { "confirmation": { "type": "string", "enum": [ "instant", "request" ] }, "summary": { "type": "string" }, "customer": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The fields of `customer` in a book request, with what each takes." }, "items": { "type": "string", "description": "How to name what is being booked: the shape of `items`." }, "answers": { "type": "array", "items": { "type": "object", "description": "One question a booking asks, with the exact way to answer it. Answer it under `answers.`.", "properties": { "id": { "type": "string", "description": "The key of the answer in `answers`." }, "label": { "type": "string", "description": "The question, as the booking page asks it." }, "type": { "type": "string", "enum": [ "text", "longtext", "email", "phone", "url", "select", "multiselect" ] }, "required": { "type": "boolean" }, "step": { "type": "integer", "description": "Which step of the booking page's form the question is on; questions of one step are asked together." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The choices of a select or multiselect. An answer is exactly one of these strings (a list of them, for a multiselect)." }, "allowOther": { "type": "boolean", "description": "A select that takes \"Other\" and the customer's own words under `otherId`." }, "otherId": { "type": "string", "description": "Where the typed words go when the answer is \"Other\"." }, "max": { "type": "integer", "description": "The longest answer, in characters." }, "maxSelections": { "type": "integer", "description": "The most choices a multiselect takes." }, "none": { "type": "string", "description": "The exact phrase that stands in for an answer when there is none." }, "format": { "type": "string", "description": "How to answer, as a sentence." }, "example": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "An answer that is accepted." } }, "required": [ "id", "label", "type", "required", "format", "example" ] }, "description": "The questions to answer in `answers`, each with its exact format and an example that passes." }, "idempotencyKey": { "type": "string", "description": "How to choose the idempotency_key of a book call: random, new for each booking, a UUID without hyphens; optional on REST, required by the MCP tool." }, "examples": { "type": [ "object", "null" ], "description": "A find_times body and a book body built from this business's own services: the shapes to copy. The values are examples, never defaults; the idempotency_key is a placeholder the door refuses, so make your own.", "properties": { "find_times": { "type": "object" }, "book": { "type": "object" } } } } }, "limits": { "type": "object" }, "cancel": { "type": "string" }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } }, "urls": { "type": "object" } }, "required": [ "name", "slug", "bookable" ] } } } }, "404": { "description": "`not_found`: no such business (or its door is off), no such booking, or the token is not the booking's. All of them are the same answer.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "429": { "description": "`rate_limited`: a limit was reached. Wait for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "500": { "description": "`internal_error`: something went wrong on the business's side. Nothing was filed; trying again later is safe.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "503": { "description": "`unavailable`: the door is unavailable right now. Try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "504": { "description": "`gateway_timeout`: the door did not answer in time (the proxy waits 8 seconds). Nothing is known about whether it acted: send a booking again with the SAME `idempotency_key`, which answers the first booking instead of making a second.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } } } }, "/agent/times": { "post": { "operationId": "findTimes", "security": [], "summary": "Open start times", "description": "The business's open start times for what is being booked, between two dates, narrowed to the customer's free windows when given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Ask for the start times that are open. Only the business's own open times come back, narrowed to the customer's free windows when given.", "properties": { "items": { "type": "array", "description": "What is being booked. May be left out only when the business offers exactly one service (a consulting business's one kind of call).", "items": { "type": "object", "description": "One service being booked. Use the `slug` of a service from the business card. For a business that works on a car, give each car its package and any add-ons as separate items that share the same `label` (the car, as a person would say it: \"2023 Porsche 911\"), and a `label` is required on every item.", "properties": { "slug": { "type": "string", "description": "The service's slug, from the card's services list.", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "description": "How many of it. Default 1.", "minimum": 1, "maximum": 50, "default": 1 }, "label": { "type": "string", "description": "What the service is for: the car (\"2023 Porsche 911\"). Required for a detailing business; leave out for a meeting.", "maxLength": 300 } }, "required": [ "slug" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 }, "from": { "type": "string", "format": "date", "description": "First day, YYYY-MM-DD, in the business's time zone (the card names it). Not in the past." }, "to": { "type": "string", "format": "date", "description": "Last day, YYYY-MM-DD. At most 14 days from `from`, counting both, and at most 60 days from today." }, "windows": { "type": "array", "description": "The customer's free time, as intervals with offsets. When given, only starts whose whole job or meeting fits inside one window come back. Leave out to see every open start.", "items": { "description": "A stretch of time the customer is free, from their own calendar. Both ends are ISO 8601 with an offset (\"2026-10-12T09:00:00-07:00\" or \"...Z\"), and the end is after the start. Written either as {start, end} or as one ISO 8601 interval string \"start/end\".", "oneOf": [ { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})/\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "An ISO 8601 interval: \"2026-10-12T09:00:00-07:00/2026-10-12T17:00:00-07:00\"." } ] }, "maxItems": 50 } }, "required": [ "from", "to" ], "additionalProperties": false, "examples": [ { "items": [ { "slug": "discovery-call" } ], "from": "2026-10-05", "to": "2026-10-11", "windows": [ { "start": "2026-10-05T08:00:00-07:00", "end": "2026-10-05T18:00:00-07:00" } ] } ] }, "example": { "items": [ { "slug": "discovery-call" } ], "from": "2026-10-05", "to": "2026-10-11", "windows": [ { "start": "2026-10-05T08:00:00-07:00", "end": "2026-10-05T18:00:00-07:00" } ] } } } }, "responses": { "200": { "description": "Open starts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "type": "string", "description": "The business's IANA time zone." }, "durationMinutes": { "type": "integer", "description": "How long the selection takes: the business's own estimate." }, "times": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "ISO 8601 with the business's offset." }, "end": { "type": "string", "description": "When the job or meeting ends, ISO 8601 with the same offset." } }, "required": [ "start", "end" ] }, "description": "Open start times, earliest first, on the business's 30-minute grid." } }, "required": [ "timezone", "durationMinutes", "times" ] } } } }, "400": { "description": "The request is not valid: `invalid_request` (the message says what to fix), `invalid_intake` (an answer to one of the business's questions; the message starts with the question) or `unknown_service`.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "404": { "description": "`not_found`: no such business (or its door is off), no such booking, or the token is not the booking's. All of them are the same answer.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "409": { "description": "`scheduling_not_configured`: the business has not set its hours or time zone, so open times cannot be worked out.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "413": { "description": "`payload_too_large`: the request body is larger than the door takes.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "422": { "description": "`duration_unknown`: the business has not set how long the selected service takes, so open times cannot be worked out. Contact it to book that service.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "429": { "description": "`rate_limited`: a limit was reached. Wait for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "500": { "description": "`internal_error`: something went wrong on the business's side. Nothing was filed; trying again later is safe.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "501": { "description": "`unsupported_flow`: the door does not serve this kind of business yet (a tint shop's page, say). Use its booking page.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "503": { "description": "`unavailable`: the door is unavailable right now. Try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "504": { "description": "`gateway_timeout`: the door did not answer in time (the proxy waits 8 seconds). Nothing is known about whether it acted: send a booking again with the SAME `idempotency_key`, which answers the first booking instead of making a second.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } } } }, "/agent/book": { "post": { "operationId": "book", "security": [], "summary": "Book", "description": "Book an open start. Answers whether the booking is confirmed or requested, what happens next, and a token to manage it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Book. The same checks as the business's booking page: a real open start, the questions the card lists, the same limits on every text.", "properties": { "items": { "type": "array", "description": "What is being booked. May be left out only when the business offers exactly one service (a consulting business's one kind of call).", "items": { "type": "object", "description": "One service being booked. Use the `slug` of a service from the business card. For a business that works on a car, give each car its package and any add-ons as separate items that share the same `label` (the car, as a person would say it: \"2023 Porsche 911\"), and a `label` is required on every item.", "properties": { "slug": { "type": "string", "description": "The service's slug, from the card's services list.", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "description": "How many of it. Default 1.", "minimum": 1, "maximum": 50, "default": 1 }, "label": { "type": "string", "description": "What the service is for: the car (\"2023 Porsche 911\"). Required for a detailing business; leave out for a meeting.", "maxLength": 300 } }, "required": [ "slug" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::00(?:\\.0+)?)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "A start time from `times`, ISO 8601 with an offset, on a whole minute: seconds, when written, are 00 (\"2026-10-12T10:00:00-07:00\" or \"2026-10-12T17:00Z\"). It is checked again, and refused with `time_not_open` if it is no longer open." }, "customer": { "type": "object", "description": "The person the booking is for. They receive the confirmation email.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Full name." }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 50, "description": "Optional, unless the business's questions say it is required." }, "time_zone": { "type": "string", "maxLength": 64, "description": "Optional IANA zone of the customer (\"Europe/London\"): a meeting's confirmation then shows their clock too." } }, "required": [ "name", "email" ], "additionalProperties": false }, "answers": { "type": "object", "description": "Answers to the questions the card lists under booking.answers, by their `id`. Each question there says its exact format and shows an example that passes: a select takes exactly one of its option strings, copied character for character; a multiselect takes a list of its option strings (at most its `maxSelections`, each once); a text, a long text, an email, a phone number and a web address each have a stated length limit; a select with `allowOther` takes \"Other\" with the customer's own words under `_other`; and a question with a `none` phrase takes exactly that phrase when there is no answer. A mobile detailer asks for `address`. Leave out when the card lists none.", "additionalProperties": true }, "agent": { "type": "object", "description": "Who is booking, so the business sees that an agent made the booking and which one.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the agent is called (\"Muse\", \"ChatGPT\")." }, "acting_for": { "type": "string", "maxLength": 120, "description": "Optional: the person it acts for, if that is not the customer." } }, "required": [ "name" ], "additionalProperties": false }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,255}$", "minLength": 32, "maxLength": 255, "description": "A key you choose: 32 to 255 letters, digits, dashes or underscores, and RANDOM, never a counter, a word or a pattern (a UUID without hyphens is right; the door refuses a key with fewer than 8 distinct characters). Repeating the call with the same key and customer email answers the first booking again, with the same manage token, instead of making a second one, so make it unguessable and new for each booking. Leave it out and one is made and returned in the answer as `idempotency_key`." } }, "required": [ "start", "customer", "agent" ], "additionalProperties": false, "examples": [ { "items": [ { "slug": "discovery-call" } ], "start": "2026-10-05T08:00:00-07:00", "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "(619) 555-0123", "time_zone": "Europe/London" }, "answers": { "business_name": "Analytical Engines Ltd", "website": "analyticalengines.example", "industry": "Professional services", "team_size": "Just me", "decider": "I decide with a partner", "pains": [ "Slow replies to new leads", "Hours of admin and data entry" ], "notes": "We lose leads that message after hours.", "timeline": "In the next three months", "budget": "Not sure yet" }, "agent": { "name": "Your agent name" }, "idempotency_key": "replace-this-with-a-fresh-random-key-0000" } ] }, "example": { "items": [ { "slug": "discovery-call" } ], "start": "2026-10-05T08:00:00-07:00", "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "(619) 555-0123", "time_zone": "Europe/London" }, "answers": { "business_name": "Analytical Engines Ltd", "website": "analyticalengines.example", "industry": "Professional services", "team_size": "Just me", "decider": "I decide with a partner", "pains": [ "Slow replies to new leads", "Hours of admin and data entry" ], "notes": "We lose leads that message after hours.", "timeline": "In the next three months", "budget": "Not sure yet" }, "agent": { "name": "Your agent name" }, "idempotency_key": "replace-this-with-a-fresh-random-key-0000" } } } }, "responses": { "200": { "description": "Booked or requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "confirmed", "requested", "cancelled", "declined", "completed", "expired" ], "description": "`confirmed`: booked. `requested`: sent to the business, which approves it or suggests another time. A repeated call (the same idempotency key) answers what the booking has become since, so it can also be `cancelled`, `declined`, `completed` or `expired`." }, "reference": { "type": "string", "description": "The booking's id." }, "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "name", "quantity" ] } }, "estimatedPrice": { "type": [ "number", "null" ], "description": "The business's estimate in its currency, or null when it quotes." }, "manage": { "type": "object", "description": "How to look at or cancel this booking later.", "properties": { "token": { "type": "string", "description": "Keep it. It is the only proof the booking is yours: send it as `Authorization: Bearer `. It is shown once." }, "url": { "type": "string", "description": "The booking's address: GET it with the token to check its state." } }, "required": [ "token", "url" ] }, "next": { "type": "string", "description": "One sentence on what happens now, for the agent to tell the customer." }, "idempotency_key": { "type": "string", "description": "The key this booking was filed under: the one you sent, or the one made for you. Send it again to repeat the call safely." }, "reason": { "type": "string", "enum": [ "time_taken" ], "description": "Present on `requested` when the business confirms at once and the time had been taken a moment before." }, "idempotent_replay": { "type": "boolean", "description": "Present and true when this is the answer to an earlier call with the same idempotency key." } }, "required": [ "status", "reference", "start", "end", "timezone", "manage", "next", "idempotency_key" ] } } } }, "400": { "description": "The request is not valid: `invalid_request` (the message says what to fix), `invalid_intake` (an answer to one of the business's questions; the message starts with the question) or `unknown_service`.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "404": { "description": "`not_found`: no such business (or its door is off), no such booking, or the token is not the booking's. All of them are the same answer.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "409": { "description": "`time_not_open`: that time is no longer open (taken, past, or outside hours); ask for times again. Or `scheduling_not_configured`: the business has not set its hours.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "413": { "description": "`payload_too_large`: the request body is larger than the door takes.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "422": { "description": "`duration_unknown`: the business has not set how long the selected service takes, so open times cannot be worked out. Contact it to book that service.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "429": { "description": "`rate_limited`: a limit was reached. Wait for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "500": { "description": "`internal_error`: something went wrong on the business's side. Nothing was filed; trying again later is safe.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "501": { "description": "`unsupported_flow`: the door does not serve this kind of business yet (a tint shop's page, say). Use its booking page.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "503": { "description": "`unavailable`: the door is unavailable right now. Try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "504": { "description": "`gateway_timeout`: the door did not answer in time (the proxy waits 8 seconds). Nothing is known about whether it acted: send a booking again with the SAME `idempotency_key`, which answers the first booking instead of making a second.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } } } }, "/agent/bookings/{reference}": { "get": { "operationId": "getBooking", "summary": "A booking's state", "description": "Check a booking made through this door. Send the booking's manage token as a bearer token.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The booking's `reference`." } ], "security": [ { "manageToken": [] } ], "responses": { "200": { "description": "The booking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "declined", "cancelled", "completed", "expired" ] }, "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" } } } }, "bookedBy": { "type": "string", "description": "The agent name the booking was made under." }, "canCancel": { "type": "boolean", "description": "Whether cancel will work. A booking the business has approved or taken in hand must be changed with the business." }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } }, "next": { "type": "string" } }, "required": [ "reference", "status", "canCancel", "next" ] } } } }, "404": { "description": "`not_found`: no such business (or its door is off), no such booking, or the token is not the booking's. All of them are the same answer.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "429": { "description": "`rate_limited`: a limit was reached. Wait for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "500": { "description": "`internal_error`: something went wrong on the business's side. Nothing was filed; trying again later is safe.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "503": { "description": "`unavailable`: the door is unavailable right now. Try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "504": { "description": "`gateway_timeout`: the door did not answer in time (the proxy waits 8 seconds). Nothing is known about whether it acted: send a booking again with the SAME `idempotency_key`, which answers the first booking instead of making a second.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } } } }, "/agent/bookings/{reference}/cancel": { "post": { "operationId": "cancelBooking", "summary": "Cancel a booking", "description": "Withdraw a request still waiting, or cancel a booking the business confirmed at once. A booking the business has approved or taken in hand answers 409 with how to reach it.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The booking's `reference`." } ], "security": [ { "manageToken": [] } ], "responses": { "200": { "description": "Cancelled (or already cancelled).", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "cancelled": { "type": "boolean", "description": "False when the booking was already cancelled." }, "next": { "type": "string" } }, "required": [ "reference", "status", "cancelled", "next" ] } } } }, "404": { "description": "`not_found`: no such business (or its door is off), no such booking, or the token is not the booking's. All of them are the same answer.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "409": { "description": "`managed_by_business`: the business has approved or taken the booking in hand, so it cannot be cancelled here; the body carries its `contact`. Or `not_cancellable`: the booking is already declined, completed or expired.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "429": { "description": "`rate_limited`: a limit was reached. Wait for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "500": { "description": "`internal_error`: something went wrong on the business's side. Nothing was filed; trying again later is safe.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } } }, "503": { "description": "`unavailable`: the door is unavailable right now. Try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } }, "504": { "description": "`gateway_timeout`: the door did not answer in time (the proxy waits 8 seconds). Nothing is known about whether it acted: send a booking again with the SAME `idempotency_key`, which answers the first booking instead of making a second.", "content": { "application/json": { "schema": { "type": "object", "description": "Every refusal, whatever its status: a sentence and a code.", "properties": { "error": { "type": "string", "description": "What to fix, in a sentence. Never what is in the way, and never an internal detail." }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_intake", "unknown_service", "not_found", "method_not_allowed", "time_not_open", "scheduling_not_configured", "managed_by_business", "not_cancellable", "payload_too_large", "duration_unknown", "rate_limited", "internal_error", "unsupported_flow", "unavailable", "gateway_timeout" ], "description": "A stable code to branch on; its status is the response's." }, "contact": { "type": "object", "description": "With `managed_by_business`: how to reach the business to change the booking.", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } }, "required": [ "error", "code" ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "security": [], "summary": "The same, as an MCP server", "description": "A stateless MCP server (Streamable HTTP, plain JSON replies) with the tools get_business, find_times, book, get_booking and cancel_booking. It answers both the `initialize` handshake of protocol 2025-06-18 and the stateless 2026-07-28 form (server/discover, the MCP-Protocol-Version header).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "A notification was accepted." } } } } }, "components": { "securitySchemes": { "manageToken": { "type": "http", "scheme": "bearer", "description": "The `manage.token` that book returned for this booking." } } }, "x-cortex-tools": [ { "name": "get_business", "title": "Get the business", "annotations": { "title": "Get the business", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "find_times", "title": "Find open times", "annotations": { "title": "Find open times", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "book", "title": "Book", "annotations": { "title": "Book", "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "get_booking", "title": "Check a booking", "annotations": { "title": "Check a booking", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "cancel_booking", "title": "Cancel a booking", "annotations": { "title": "Cancel a booking", "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true } } ] }