{ "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": "Demo Tint Co: booking for AI agents", "version": "1.5.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 (or, by email, confirms with the customer); 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/demo-tint", "description": "Demo Tint Co, 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; unavailableReason says how the customer can book instead." }, "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" ], "description": "Where a business that comes to the customer works, in words." }, "serviceAreaList": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The cities, counties and ZIP codes the business serves, when it lists them (\"Poway\", \"Portland OR\" for a city in one state, \"San Diego County\", \"92064\"): an address outside them is refused (`outside_service_area`). Null when it lists none." }, "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", "glass" ], "description": "`glass`: a window tint service; its `price` is the lowest, and the full table is in `tint`." } }, "required": [ "slug", "name", "kind" ] } }, "tint": { "type": "object", "description": "A window tint business only: what a `tint` request is chosen from. Each window service's price is prices[vehicle class id][film slug], or null when the shop quotes it.", "properties": { "vehicleClasses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "examples": { "type": "string", "description": "Models in the class." } }, "required": [ "id", "label" ] } }, "windowGroups": { "type": "array", "description": "The window groups the shop's services cover; a shade can be chosen for each.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "glass": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "windowGroups": { "type": "array", "items": { "type": "string" } }, "durationMinutes": { "type": [ "integer", "null" ] }, "prices": { "type": "object", "description": "prices[vehicle class id][film slug]: a number, or null when the shop quotes it." } }, "required": [ "slug", "name", "windowGroups", "prices" ] } }, "films": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "housePick": { "type": "boolean", "description": "The shop's own suggestion." }, "shades": { "type": "array", "description": "The shades it is stocked in: the percentage of light let through, and what that is like to live with.", "items": { "type": "object", "properties": { "shade": { "type": "integer" }, "name": { "type": "string" }, "line": { "type": "string" } }, "required": [ "shade", "name", "line" ] } } }, "required": [ "slug", "name", "shades" ] } } } }, "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`, or of `tint` for a window tint business." }, "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" } } }, "address": { "type": [ "string", "null" ], "description": "For a business that comes to the customer: how to check the service address before booking. Null for one that does not." }, "payment": { "type": "string", "description": "What is paid, and when. The door takes no payment: nothing is paid when booking." } } }, "limits": { "type": "object" }, "cancel": { "type": "string" }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } }, "urls": { "type": "object", "properties": { "humanPage": { "type": [ "string", "null" ], "description": "Where a person books this business: its booking page on this host, or its own https page. Null when it names none: then there is no page to send the customer to, and contact says how to reach the business." } } } }, "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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). A window tint business takes `tint` instead, never items.", "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 }, "tint": { "type": "object", "description": "What is being booked at a window tint business, in place of `items` (the card says which a business takes): the class of the customer's car, the windows, the film and the shade, each chosen from the card's `tint` section. The business prices and times it; a shade never changes the price. Choosing the front two windows and the rear sides books the full vehicle, at its price.", "properties": { "vehicle_class": { "type": "string", "enum": [ "coupe", "sedan", "truck", "suv", "suv_xl" ], "description": "The class of the customer's car: an id from the card's tint.vehicleClasses, each of which lists example models." }, "glass": { "type": "array", "description": "The windows to tint: slugs from the card's tint.glass, each once.", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "film": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The film: a slug from the card's tint.films." }, "shade": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The percentage of light the film lets through (lower is darker), for every window: one of the chosen film's shades." }, "zone_shades": { "type": "object", "description": "Optional: a different shade for a window group the chosen glass covers, by the group's id from the card's tint.windowGroups ({\"fr\": 35, \"rr\": 20}). Each is one of the film's shades; a group left out takes `shade`.", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "required": [ "vehicle_class", "glass", "film", "shade" ], "additionalProperties": false }, "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": [ { "tint": { "vehicle_class": "sedan", "glass": [ "full-vehicle" ], "film": "ceramic", "shade": 35 }, "from": "2026-10-15", "to": "2026-10-21", "windows": [ { "start": "2026-10-15T08:00:00-07:00", "end": "2026-10-15T17:00:00-07:00" } ] } ] }, "example": { "tint": { "vehicle_class": "sedan", "glass": [ "full-vehicle" ], "film": "ceramic", "shade": 35 }, "from": "2026-10-15", "to": "2026-10-21", "windows": [ { "start": "2026-10-15T08:00:00-07:00", "end": "2026-10-15T17: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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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. For a business that comes to the customer: `address_invalid` (Google could not confirm the address; check it with the customer), `address_unconfirmed` (Google corrected it; the message gives the corrected address to confirm with the customer and book with): for either, a customer who says theirs is right as given books it with answers.address_confirmed: true. `outside_service_area`: do not book. For a pet care business: `service_is_a_stay` (a stay, which is requested with the business itself) or `service_not_offered` (a service not booked through the door), whose message says what the customer can do instead, and `meet_greet_required` (a new customer books the Meet & Greet first).", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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 consulting business that does not meet online, 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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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/address": { "post": { "operationId": "checkAddress", "security": [], "summary": "Check a service address", "description": "For a business that comes to the customer: whether Google confirms the address, the address to book with, its Place ID, and whether it is inside the area the business serves. Check before booking; book checks it again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Check a service address before booking a business that comes to the customer: whether Google confirms it, the address to book with, and whether it is inside the area the business serves.", "properties": { "address": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500, "description": "The address as one line: \"123 Main St, Poway, CA 92064\"." }, { "type": "object", "description": "The address as fields, in any one of three spellings: schema.org PostalAddress (streetAddress, extendedAddress, addressLocality, addressRegion, postalCode, addressCountry), the same in snake_case (street_address, extended_address, address_locality, address_region, postal_code, address_country), or line_one, line_two, city, state, postal_code, country. A street is required. Or send `place_id`, a Google Place ID saved from an earlier check of this customer's address, with the apartment or unit as extended_address if there is one.", "properties": { "street_address": { "type": "string", "maxLength": 200 }, "extended_address": { "type": "string", "maxLength": 200, "description": "Apartment, suite or unit." }, "address_locality": { "type": "string", "maxLength": 200, "description": "The city." }, "address_region": { "type": "string", "maxLength": 200, "description": "The state, as its two-letter code." }, "postal_code": { "type": "string", "maxLength": 200 }, "address_country": { "type": "string", "maxLength": 200, "description": "A two-letter country code; US when left out." }, "place_id": { "type": "string", "maxLength": 300, "description": "A Google Place ID from an earlier check, alone." } }, "additionalProperties": true } ] } }, "required": [ "address" ], "additionalProperties": false, "examples": [ { "address": "123 Main St, Poway, CA 92064" }, { "address": { "street_address": "123 Main St", "address_locality": "Poway", "address_region": "CA", "postal_code": "92064" } } ] } } } }, "responses": { "200": { "description": "The check.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "ok", "confirm", "invalid", "unverified" ], "description": "`ok`: Google confirmed it. `confirm`: Google corrected it; read the corrected `address` to the customer and use it if they agree. `invalid`: Google could not confirm it; check it with the customer (if they say it is right as given, book it with answers.address_confirmed: true). `unverified`: it could not be checked right now; it can still be booked, and the business reviews it." }, "address": { "type": [ "string", "null" ], "description": "The address to book with, as answers.address: Google's standard form when it checked it." }, "place_id": { "type": [ "string", "null" ], "description": "Google's Place ID for it. Save it with the address for this customer; next time, send it (with the apartment or unit as extended_address, if there is one)." }, "plus_code": { "type": [ "string", "null" ], "description": "Its Plus Code (an open code for the spot, about 14 metres square)." }, "ask_for_unit": { "type": "boolean", "description": "True when Google suggests asking for an apartment, suite or unit number." }, "service_area": { "type": "object", "properties": { "set": { "type": "boolean", "description": "Whether the business lists the cities, counties and ZIP codes it serves." }, "in_area": { "type": [ "boolean", "null" ], "description": "Whether the address is inside that area; null when it cannot be told (the business decides)." }, "matched": { "type": [ "string", "null" ], "description": "The city, county or ZIP code of the list it matched." }, "area": { "type": [ "string", "null" ], "description": "The area, in words." } }, "required": [ "set", "in_area", "matched", "area" ] }, "bookable": { "type": "boolean", "description": "Whether book takes `address` as it is. False when it is invalid (bookable only with answers.address_confirmed: true) or outside the area (not bookable)." }, "next": { "type": "string", "description": "What to do next, in one or two sentences." } }, "required": [ "verdict", "address", "place_id", "plus_code", "ask_for_unit", "service_area", "bookable", "next" ] } } } }, "400": { "description": "`invalid_request`: the address is missing or malformed, or this business does not come to the customer (it needs no address).", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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 consulting business that does not meet online, 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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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). A window tint business takes `tint` instead, never items.", "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 }, "tint": { "type": "object", "description": "What is being booked at a window tint business, in place of `items` (the card says which a business takes): the class of the customer's car, the windows, the film and the shade, each chosen from the card's `tint` section. The business prices and times it; a shade never changes the price. Choosing the front two windows and the rear sides books the full vehicle, at its price.", "properties": { "vehicle_class": { "type": "string", "enum": [ "coupe", "sedan", "truck", "suv", "suv_xl" ], "description": "The class of the customer's car: an id from the card's tint.vehicleClasses, each of which lists example models." }, "glass": { "type": "array", "description": "The windows to tint: slugs from the card's tint.glass, each once.", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "film": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The film: a slug from the card's tint.films." }, "shade": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The percentage of light the film lets through (lower is darker), for every window: one of the chosen film's shades." }, "zone_shades": { "type": "object", "description": "Optional: a different shade for a window group the chosen glass covers, by the group's id from the card's tint.windowGroups ({\"fr\": 35, \"rr\": 20}). Each is one of the film's shades; a group left out takes `shade`.", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "required": [ "vehicle_class", "glass", "film", "shade" ], "additionalProperties": false }, "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 business that comes to the customer (a mobile detailer or tint shop) asks for `address`: check it first (POST /agent/address, the MCP tool check_address) and send the `address` that answers. The address is checked again here, and refused with `address_invalid`, `address_unconfirmed` (with the corrected address) or `outside_service_area`. When Google could not confirm it or corrected it, and the customer says theirs is right as they gave it, send theirs with `address_confirmed: true`: it is filed as given, for the business to check (never past `outside_service_area`). 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": [ { "tint": { "vehicle_class": "sedan", "glass": [ "full-vehicle" ], "film": "ceramic", "shade": 35 }, "start": "2026-10-15T08:00:00-07:00", "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "(619) 555-0123" }, "agent": { "name": "Your agent name" }, "idempotency_key": "replace-this-with-a-fresh-random-key-0000" } ] }, "example": { "tint": { "vehicle_class": "sedan", "glass": [ "full-vehicle" ], "film": "ceramic", "shade": 35 }, "start": "2026-10-15T08:00:00-07:00", "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "(619) 555-0123" }, "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 business that takes its bookings by email confirms it with the customer itself; `next` says which). 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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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. For a business that comes to the customer: `address_invalid` (Google could not confirm the address; check it with the customer), `address_unconfirmed` (Google corrected it; the message gives the corrected address to confirm with the customer and book with): for either, a customer who says theirs is right as given books it with answers.address_confirmed: true. `outside_service_area`: do not book. For a pet care business: `service_is_a_stay` (a stay, which is requested with the business itself) or `service_not_offered` (a service not booked through the door), whose message says what the customer can do instead, and `meet_greet_required` (a new customer books the Meet & Greet first).", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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 consulting business that does not meet online, 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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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", "address_invalid", "address_unconfirmed", "outside_service_area", "meet_greet_required", "service_is_a_stay", "service_not_offered", "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, check_address, 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": "check_address", "title": "Check an address", "annotations": { "title": "Check an address", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "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 } } ] }