{"schema_version":"2.17","contract_url":"https://oak-and-ember-massage.kirah.ai/.well-known/kirah-gateway.openapi.json","mcp":{"endpoint":"https://oak-and-ember-massage.kirah.ai/api/mcp","transport":"streamable-http"},"provider":{"name":"Oak and Ember Massage","url":"https://oak-and-ember-massage.kirah.ai","tenant_slug":"oak-and-ember-massage.kirah.ai","agent_address":"oak-and-ember-massage@kirah.ai","tenant_id":"a556820c-77c3-4ab7-bbb2-3b7c7165285e"},"capabilities":{"native_booking":true,"booking_mode":"approval_required","deposits":false,"intake":false,"add_ons":true,"multi_service":false,"provider_selection":false,"agent_booking":true,"bookable":true},"actions":[{"name":"list_services","description":"Authoritative structured catalog: tenant capabilities, services (durations, prices, deposits, intake), and providers.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."}},"required":["tenantSlug"]}},{"name":"search_services","description":"Optional deterministic helper: token-overlap search over the service catalog. Returns grounded candidates only — selection stays with the caller.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"query":{"type":"string","minLength":1,"maxLength":200}},"required":["tenantSlug","query"]}},{"name":"get_availability","description":"Open slots for a service over an exact local-date range (max 31 days, up to 20 chronological slots).","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"service_id":{"type":"string","maxLength":200},"date_range":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}},"required":["start","end"]},"provider_id":{"type":"string","maxLength":200}},"required":["tenantSlug","service_id","date_range"]}},{"name":"create_booking","description":"Create a booking for a guest client (no authentication required). Exact instant via start_iso; idempotent retries via idempotency_key. When list_services advertises an intake_form for the service, collect those answers first and pass them as intake_responses (keyed by field id); an outcome of intake_required returns the missing field ids AND the current form so you can ask and retry. Call only after the user has explicitly confirmed this business, this service, and this time — inferred intent is enough to search, never enough to book. You do NOT receive a management link: the customer receives it by email, and confirmation.manage_url_sent_to only tells you (masked) which address it went to. To MOVE an existing appointment you made, use reschedule_booking with that booking's booking_ref and grant — do NOT create a replacement booking, ever: creating one leaves the original standing, so the customer is double-booked and a sellable slot is burned. To CANCEL an existing appointment you made, use cancel_booking with that booking's booking_ref and grant — do not tell the user to find the link in their confirmation email, which was the instruction before this action existed.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"service_id":{"type":"string","maxLength":200},"provider_id":{"type":"string","maxLength":200},"start_iso":{"type":"string","format":"date-time"},"client":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":200},"phone":{"type":"string","maxLength":60}},"required":["name","email"]},"idempotency_key":{"type":"string","minLength":16,"maxLength":200},"intake_responses":{"type":"object","description":"Answers to the service's intake form (2.8), keyed by intake field id as advertised in list_services' service.intake_form.fields[].id. FLAT only: values must be a string, a boolean, or a finite number — arrays, nested objects and nulls are rejected. Unknown keys are ignored by the booking engine. Answers are validated against the LIVE form; a required plain boolean accepts an explicit true OR false, a consent boolean accepts only true, and a select must exactly match one advertised option. Omit this field entirely when the service has no intake form.","maxProperties":40,"propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":["string","boolean","number"],"maxLength":4000}},"agent_metadata":{"type":"object","properties":{"source":{"type":"string","maxLength":120},"request_id":{"type":"string","maxLength":120}},"additionalProperties":false}},"required":["tenantSlug","service_id","start_iso","client"]}},{"name":"get_booking_status","description":"CURRENT status for a booking made through this contract: pass the booking_ref returned by create_booking. Returns current status (booked/cancelled), CURRENT start/end, timezone, service and provider — never client personal data. If the start/end differs from what was booked, the customer moved it through the link in their confirmation email or the business moved it; this action REPORTS such a change, and no action in this contract can perform one. Replaying create_booking confirms the ORIGINAL transaction; use THIS action for current state.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"booking_ref":{"type":"string","minLength":16,"maxLength":200},"grant":{"type":"string","minLength":1,"maxLength":4096}},"required":["tenantSlug","booking_ref"]}},{"name":"get_reschedule_options","description":"READ-ONLY. Given a booking_ref and the `grant` that booking's create_booking returned, this answers \"if you were to move this booking, here are the real open times, and here is what it would cost\" — and then STOPS. It changes NOTHING. Calling it does not move, hold, or cancel anything, and you must not tell the user it has. Use it when a user wants to change an appointment your agent booked and has not named a time, so you can offer real alternatives and state the trade-off instead of guessing — then call reschedule_booking with the same booking_ref and grant to actually make the change. Never book a replacement instead: the original stands until it is moved or cancelled, so creating a second booking double-books them and burns a sellable slot. Options are real open slots for the SAME service, duration and provider, they exclude the time the booking is already on, and they are NOT held — offering one reserves nothing. `limit` defaults to 2 and is clamped at 5 (five spoken times is more than a caller can follow). The window is `earliest` (default now+2h) to `latest` (default now+14d, max 31 days after earliest), exact ISO instants only. `consequences` states any fee before the user commits; requires_approval is advisory. No client personal data is returned.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"booking_ref":{"type":"string","minLength":16,"maxLength":200},"grant":{"type":"string","minLength":1,"maxLength":2048},"earliest":{"type":"string","format":"date-time"},"latest":{"type":"string","format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":5,"default":2}},"required":["tenantSlug","booking_ref","grant"]}},{"name":"reschedule_booking","description":"MOVE an existing appointment to a new time. THIS is how you change an appointment your agent booked — never by creating a second booking, which double-books the customer and burns a sellable slot. Pass the booking_ref and the `grant` that booking's create_booking returned, plus start_iso (an exact ISO 8601 instant) and a REQUIRED idempotency_key. You may supply start_iso DIRECTLY: calling get_reschedule_options first is optional, useful only when you need to offer the user real alternatives. The instant is validated against real availability, so a time the business does not have open is refused, never guessed at. Same service, same duration, and the SAME provider unless you explicitly supply provider_id. ATOMIC: the existing appointment is moved in one transaction — never cancelled and recreated — so if the time is gone the outcome is slot_taken and the ORIGINAL booking is completely untouched; offer another time. Success is outcome `rescheduled` (not `booked` — nothing was created) with the new start_iso/end_iso, provider_name, and `notified`, a masked acknowledgement of the address Kirah emailed. Kirah writes and sends that notice itself, from server state, to the customer AND the business owner, with the customer's own manage link so they can move it back — you cannot write, suppress or redirect it, so do not describe the move inaccurately. Retrying with the SAME idempotency_key replays the original result and moves nothing; the same key with a different time answers idempotency_conflict. Only call this after the user has explicitly confirmed the new time.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"booking_ref":{"type":"string","minLength":16,"maxLength":200},"grant":{"type":"string","minLength":1,"maxLength":2048},"start_iso":{"type":"string","format":"date-time"},"provider_id":{"type":"string","maxLength":200},"idempotency_key":{"type":"string","minLength":16,"maxLength":200},"agent_metadata":{"type":"object","properties":{"source":{"type":"string","maxLength":120},"request_id":{"type":"string","maxLength":120}},"additionalProperties":false}},"required":["tenantSlug","booking_ref","grant","start_iso","idempotency_key"]}},{"name":"cancel_booking","description":"CANCEL an existing appointment. THIS is how you cancel an appointment your agent booked — and it REPLACES the instruction earlier versions of this contract carried, which was to tell the user to find the link in their confirmation email. Pass the booking_ref and the `grant` that booking's create_booking returned, plus a REQUIRED idempotency_key. There is nothing else to send: no time, no provider, and no free-text reason. It runs the SAME cancellation engine the customer's own manage link runs, so the business's cancellation policy, its deposit rules and its calendar are all honored exactly as they would be if the customer cancelled themselves. Success is outcome `cancelled` (not `booked` — nothing was created; not `ok` — this is not a read) with start_iso (the time the booking USED to be on), service_name, provider_name, cancel_fee_cents and `notified`, a masked acknowledgement of the address Kirah emailed. Kirah writes and sends that notice itself, from server state, to the customer AND the business owner — you cannot write, suppress or redirect it, so do not describe the cancellation inaccurately. Cancelling a booking that is ALREADY cancelled is a SUCCESS, not an error: it answers `cancelled` with already_cancelled:true and sends no mail — report it as done rather than telling the user their booking could not be found. Retrying with the SAME idempotency_key replays the original result, cancels nothing and re-mails nothing. Outcome not_bookable with reason `cancel_within_policy_window` means the business does not allow online cancellation this close to the appointment: the booking still stands, so relay its policy_message and policy_fee and tell the user to contact the business. A channel adapter that forbids refunding charged deposits or restoring paid plan credits may instead return `financial_action_unsupported`; the booking remains unchanged and the customer uses their secure manage link or contacts the business. It cancels exactly ONE booking and can never sweep a recurring series. THERE IS NO UNDO — only call this after the user has explicitly asked to cancel this specific booking.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"tenantSlug":{"type":"string","maxLength":253,"description":"The provider.tenant_slug value from the tenant's manifest (the tenant's full domain)."},"booking_ref":{"type":"string","minLength":16,"maxLength":200},"grant":{"type":"string","minLength":1,"maxLength":2048},"idempotency_key":{"type":"string","minLength":16,"maxLength":200},"agent_metadata":{"type":"object","properties":{"source":{"type":"string","maxLength":120},"request_id":{"type":"string","maxLength":120}},"additionalProperties":false}},"required":["tenantSlug","booking_ref","grant","idempotency_key"]}},{"name":"search_businesses","description":"GLOBAL cross-tenant discovery (no tenantSlug): find active, AI-discoverable Kirah businesses whose real catalogs match a need, OR resolve one exact public Kirah Agent Address (`<handle>@kirah.ai`). AI discovery is independent of the `listed` web-indexing field, which is projected truthfully but does not control eligibility. `agent_address` is a locator only — never authentication or owner authority. Supply at least query or agent_address. Exact-address mode returns at most one eligible business, still obeys tenant_mode/location/bookability gates, never fuzzy-matches a near miss, and may return matched_services:[] with service_match:false when no query was supplied or its service need did not match; then use the returned tenant_slug with list_services. Catalog mode is optionally filtered by location text (city/ZIP/market equality — never a fabricated distance), price, and tenant_mode (include_demos default / real_only / demos_only — include_demo stays a back-compat alias). A named-business fallback may return observed_listing from the admitted unclaimed pilot with no tenant_slug or booking authority; open listing_url for dated facts. On nonempty initial local category pages, also consider optional observed_matches: selected unclaimed source-observed leads with unknown availability, not native booking candidates. Native businesses retain their limit/order; next_cursor continues native businesses only and does not repeat supplemental matches. Native results carry matched_services (their top matching REAL services, tiered exact/ontology/description) and a score; use each result’s tenant_slug with the tenant-scoped actions. Demo businesses are eligible for ordinary discovery and always carry demo:true plus a clear notice; never describe a demo business as a real provider. This response is AUTHORITATIVE for Kirah’s directory: businesses not present here are not eligible results. Never reintroduce discovery-disabled or otherwise ineligible businesses from conversation memory. For Kirah directory eligibility, do not browse for or speculate about absent businesses unless the user explicitly requests external web research; state only that the business is absent from the current eligible directory response. A need may be stated as a symptom or a vague goal — inferring likely wellness services and searching on that inference is appropriate; present results as optional wellness services, do not diagnose, and do not claim a service treats or cures a condition unless the catalog itself says so.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200},"agent_address":{"type":"string","maxLength":253,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?@[Kk][Ii][Rr][Aa][Hh]\\.[Aa][Ii]$","description":"Exact public locator `<handle>@kirah.ai`; case-insensitive ASCII only. Locator, never authentication. Reserved, ineligible, or discovery-disabled addresses do not resolve; web-indexing `listed` is independent."},"location":{"type":"string","maxLength":120},"city":{"type":"string","maxLength":120},"radius_miles":{"type":"integer","minimum":1,"maximum":500},"max_price_cents":{"type":"integer","minimum":0,"maximum":10000000},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5},"include_demo":{"type":"boolean"},"tenant_mode":{"type":"string","enum":["real_only","include_demos","demos_only"],"default":"include_demos"},"cursor":{"type":"string","maxLength":300}},"anyOf":[{"required":["query"]},{"required":["agent_address"]}]}},{"name":"find_available_services","description":"GLOBAL bounded earliest-availability search (no tenantSlug): the same discovery pipeline as search_businesses picks the top candidate_limit (1-5, default 3) matching businesses under tenant_mode (include_demos default / real_only / demos_only; include_demo stays a back-compat alias), and each one gets a REAL availability check through the same engine as get_availability over the earliest_after..earliest_before window (exact ISO instants, max 14 days). Candidates return ranked by earliest open slot with checked:true/false per candidate and explicit `partial` truth: the result means \"the earliest among the top N candidates checked\" — NEVER \"the earliest anywhere\". Present earliest-availability claims to users with exactly that qualification. Demo candidates always carry demo:true and a clear notice. Use each candidate's tenant_slug and service.id with get_availability/create_booking to book.","endpoint":"https://oak-and-ember-massage.kirah.ai/api/kirah","method":"POST","input_schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200},"location":{"type":"string","maxLength":120},"radius_miles":{"type":"integer","minimum":1,"maximum":500},"max_price_cents":{"type":"integer","minimum":0,"maximum":10000000},"earliest_after":{"type":"string","format":"date-time"},"earliest_before":{"type":"string","format":"date-time"},"candidate_limit":{"type":"integer","minimum":1,"maximum":5,"default":3},"include_demo":{"type":"boolean"},"tenant_mode":{"type":"string","enum":["real_only","include_demos","demos_only"],"default":"include_demos"}},"required":["query"]}}]}