{"openapi":"3.1.0","info":{"title":"Amir Khalilii guest agent API","version":"2026-05-27.stage1","description":"For AI assistants: first read https://tobira.ai/@khalilii/for-ai (facts, catalog with prices and ready actions in one short page). For anything it does not answer, talk to this agent through the guest JSON API at https://tobira.ai/api/v1/agents/khalilii/guest-agent.json: send each message with wait_seconds: 25 to get the reply in the same response, and poll with after=<last message id> to get only new messages. It is faster than the web chat, which is for humans, and is the only entry for AI-assistant services and consultation preparation.\nSite index: https://tobira.ai/@khalilii/for-ai/index\nPublic, unauthenticated guest transport. Visiting AI assistants remain untrusted guests; payment is a human action."},"servers":[{"url":"https://tobira.ai"}],"paths":{"/api/v1/guest/session":{"post":{"operationId":"createGuestSession","parameters":[{"name":"client","in":"header","required":false,"schema":{"type":"string","minLength":2,"maxLength":57,"description":"Optional declared agent product identifier, without personal data; analytics only. Stored lowercase: 2-40 ASCII letters, digits or hyphens starting with a letter, at most 4 digits before an optional /version (1-16 ASCII letters, digits, dots or hyphens starting with a digit). No colons, spaces, @ or +. Invalid supplied values become other."}},{"name":"model","in":"header","required":false,"schema":{"type":"string","minLength":2,"maxLength":57,"description":"Optional declared model identifier, without personal data; analytics only. Stored lowercase: 2-40 ASCII letters, digits or hyphens starting with a letter, at most 4 digits before an optional /version (1-16 ASCII letters, digits, dots or hyphens starting with a digit). No colons, spaces, @ or +. Invalid supplied values become other."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSession"}}}},"responses":{"201":{"description":"Guest session created"},"4XX":{"description":"Validation, rate, or quota error"}}}},"/api/v1/guest/message":{"post":{"operationId":"sendGuestMessage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage"}}}},"responses":{"200":{"description":"Message accepted"},"4XX":{"description":"Validation or rate error"}}}},"/api/v1/guest/messages":{"get":{"operationId":"pollGuestMessages","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Guest-visible conversation messages"}}}},"/api/v1/guest/action":{"post":{"operationId":"runGuestAction","parameters":[{"name":"Authorization","in":"header","required":false,"description":"Bearer guest_session_token. The same token may instead be sent in the JSON body.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestAction"}}}},"responses":{"200":{"description":"Action result; action does not end the guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestActionResult"}}}},"4XX":{"description":"Validation, rate, quota, or unavailable-action error"}}}}},"components":{"schemas":{"CreateSession":{"type":"object","required":["handle","visitor_type","transport"],"properties":{"client":{"type":"string","minLength":2,"maxLength":57,"description":"Optional declared agent product identifier, without personal data; analytics only. Stored lowercase: 2-40 ASCII letters, digits or hyphens starting with a letter, at most 4 digits before an optional /version (1-16 ASCII letters, digits, dots or hyphens starting with a digit). No colons, spaces, @ or +. Invalid supplied values become other."},"model":{"type":"string","minLength":2,"maxLength":57,"description":"Optional declared model identifier, without personal data; analytics only. Stored lowercase: 2-40 ASCII letters, digits or hyphens starting with a letter, at most 4 digits before an optional /version (1-16 ASCII letters, digits, dots or hyphens starting with a digit). No colons, spaces, @ or +. Invalid supplied values become other."},"handle":{"type":"string","const":"khalilii"},"visitor_type":{"type":"string","const":"visitor_ai_agent"},"transport":{"type":"string","const":"json_guest_api"},"source":{"type":"string","enum":["public_address","site_agent"]},"response_format":{"type":"string","enum":["text","markdown","json","json_with_structured"]}}},"SendMessage":{"type":"object","required":["token","content"],"properties":{"token":{"type":"string"},"content":{"type":"string","minLength":1},"wait_seconds":{"type":"integer","minimum":0,"maximum":25,"default":0}}},"GuestAction":{"type":"object","required":["action"],"properties":{"token":{"type":"string","description":"Guest session token; optional when sent as a Bearer token."},"action":{"type":"string","enum":["submit_authorized_contact"]},"input":{"oneOf":[{"$ref":"#/components/schemas/SubmitAuthorizedContactInput"}]}}},"ListConsultationsInput":{"type":"object","additionalProperties":false},"GuestActionResult":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string","enum":["submit_authorized_contact"]},"types":{"type":"array","items":{"$ref":"#/components/schemas/ConsultationType"}},"booking_id":{"type":"string","description":"Retain this ID for check_booking_status."},"state":{"type":"string","enum":["lead_captured","booking_preparing","booking_prepared","payment_pending","booking_confirmed"]},"requires_user_payment":{"type":"boolean"},"checkout_url":{"type":"string","format":"uri","pattern":"^https://","description":"Human payment handoff. Never substitute a booking status page or construct a payment URL."},"code":{"type":"string","description":"Inspect on failure; HTTP success alone is not booking confirmation."}}},"ConsultationType":{"type":"object","required":["id","name","questionnaire","answers_schema"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"questionnaire":{"type":"array","items":{"$ref":"#/components/schemas/BookingQuestion"}},"answers_schema":{"type":"object"},"preparation_guidance":{"type":"string","description":"Consultation preparation advice for AI-assistant services; booking is not blocked."}}},"BookingQuestion":{"type":"object","required":["id","label","type"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","single","multi","country"]},"required":{"type":"boolean"},"multiple":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}}}},"ListAvailableSlotsInput":{"type":"object","required":["type_id"],"description":"Supply both from and to, or omit both to use days from the current time.","dependentRequired":{"from":["to"],"to":["from"]},"properties":{"type_id":{"type":"string"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"tz":{"type":"string","default":"UTC"},"days":{"type":"integer","minimum":1,"maximum":31,"default":7}}},"PrepareBookingInput":{"type":"object","required":["type_id","start","name","email","authorized_by_user","idempotency_key"],"properties":{"type_id":{"type":"string"},"start":{"type":"string","format":"date-time"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"tz":{"type":"string"},"answers":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true}]}},"note":{"type":"string"},"authorized_by_user":{"type":"boolean","const":true},"idempotency_key":{"type":"string","minLength":1,"description":"Stable key reused for retries; prevents a duplicate booking."}}},"SubmitAuthorizedContactInput":{"type":"object","required":["email","authorized_by_user"],"properties":{"email":{"type":"string","format":"email"},"authorized_by_user":{"type":"boolean","const":true}}},"CheckBookingStatusInput":{"type":"object","required":["booking_id"],"properties":{"booking_id":{"type":"string"}}}}},"x-tobira":{"guest_agent_json":"https://tobira.ai/api/v1/agents/khalilii/guest-agent.json","conversation_actions":["ask_question"],"actions":["ask_question","submit_authorized_contact"],"action_api_actions":["submit_authorized_contact"],"conversation":{"mode":"multi_turn","soft_limit":30,"grace":5,"hard_cap":50,"actions_do_not_end_session":true},"languages":["English"],"consent":{"authorized_by_user_required":true,"text":"Obtain the user’s explicit authorization before submitting their contact details or preparing a booking."},"limits":{"soft_limit":30,"grace":5,"hard_cap":50},"protocol_state":"Returned in session, message, poll, and action responses; includes turns_remaining when available.","turns_remaining":"Number of guest turns before the current soft/hard limit; absent when unavailable.","booking_states":["lead_captured","booking_prepared","payment_pending","booking_confirmed"],"booking_transient_states":["booking_preparing"],"booking_types":[],"payment_pending_requires_checkout_url":true,"payment_is_human_action":true}}