{"openapi":"3.1.0","info":{"title":"Tobira guest agent API","version":"2026-05-27.stage1","description":"For AI assistants: first read https://tobira.ai/@tobira-ai/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/tobira-ai/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. This agent has published services for AI assistants.\nSite index: https://tobira.ai/@tobira-ai/for-ai/index\nPublic, unauthenticated guest transport. Visiting AI assistants remain untrusted guests; payment is a human action."},"servers":[{"url":"https://tobira.ai"}],"paths":{"/@tobira-ai/ask":{"get":{"operationId":"askPublicQuestionReadOnly","description":"Single-turn, read-only public answer. This endpoint cannot book, capture contact details, or notify the owner. Tobira does not add q to product analytics, but the full request URL may still appear in CDN, proxy, server, or browser history and logs.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000}},{"name":"client","in":"query","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":"query","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."}},{"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."}}],"responses":{"200":{"description":"Public-safe answer as text/plain or application/json according to Accept."},"404":{"description":"Agent not found or this per-agent surface is disabled."},"429":{"description":"Public request budget exceeded."}}}},"/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":"tobira-ai"},"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":["list_consultations","list_available_slots","prepare_booking","submit_authorized_contact","check_booking_status"]},"input":{"oneOf":[{"$ref":"#/components/schemas/ListConsultationsInput"},{"$ref":"#/components/schemas/ListAvailableSlotsInput"},{"$ref":"#/components/schemas/PrepareBookingInput"},{"$ref":"#/components/schemas/SubmitAuthorizedContactInput"},{"$ref":"#/components/schemas/CheckBookingStatusInput"}]}}},"ListConsultationsInput":{"type":"object","additionalProperties":false},"GuestActionResult":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string","enum":["list_consultations","list_available_slots","prepare_booking","submit_authorized_contact","check_booking_status"]},"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."}},"oneOf":[{"properties":{"type_id":{"const":"demo-with-vlad"},"answers":{"type":"object","additionalProperties":false,"properties":{"full_name":{"type":"string","maxLength":240,"minLength":1},"linkedin":{"type":"string","maxLength":240},"agent_tasks":{"type":"array","items":{"type":"string","enum":["Answer visitors' questions","Book calls and demos","Capture leads","Take payments","Support customers","Talk to AI assistants"]},"minItems":1,"uniqueItems":true},"team_size":{"type":"string","enum":["Just me","2–10","11–50","51–200","200+"]},"website":{"type":"string","maxLength":240}},"required":["full_name"]}},"required":["answers"]},{"properties":{"type_id":{"const":"ai-advisory-60"},"answers":{"type":"object","additionalProperties":false,"properties":{"full_name":{"type":"string","maxLength":240,"minLength":1},"linkedin":{"type":"string","maxLength":240},"goal":{"type":"string","enum":["Find where AI pays off first","Get my team using AI","Plan a pilot or rollout","Review an AI project we run","Startup product or strategy","Something else"]},"company_size":{"type":"string","enum":["Startup, under 10","10–50","51–250","251–1,000","1,000+"]},"company":{"type":"string","maxLength":240}},"required":["full_name"]}},"required":["answers"]},{"properties":{"type_id":{"not":{"enum":["demo-with-vlad","ai-advisory-60"]}}}}]},"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/tobira-ai/guest-agent.json","conversation_actions":["ask_question"],"actions":["ask_question","list_consultations","list_available_slots","prepare_booking","submit_authorized_contact","check_booking_status"],"action_api_actions":["list_consultations","list_available_slots","prepare_booking","submit_authorized_contact","check_booking_status"],"conversation":{"mode":"multi_turn","soft_limit":30,"grace":5,"hard_cap":50,"actions_do_not_end_session":true},"languages":["English","Russian"],"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":[{"i18n":{"ru":{"name":"Демо с Владом · 30 мин · Бесплатно","bullets":["Черновик агента на вашем сайте","Как внедрить его в ваш бизнес и лучше обучить","Тарифы, настройка и ваша цена","Как он отвечает людям и их ИИ-ассистентам"],"category":"Демо","description":"Для компаний, которым нужен агент на сайте: отвечает людям и их ИИ-ассистентам и записывает на звонки. Придём с черновиком агента на вашем сайте и обсудим, как внедрить его в ваш бизнес и как лучше его обучить.","route_question":"Что будет на бесплатном демо с Владом и как записаться?"}},"id":"demo-with-vlad","name":"Demo with Vlad · 30 min","price":0,"currency":"USD","description":"See a draft agent built on your own website answer real questions from your customers and their AI agents. Then we map how to launch it, how to train it and what it would cost.","category":"Demo","image_url":"https://tobira.ai/api/v1/agents/tobira-ai/widget-image/80d5c9d5f5b7d925abda0450da8260f4eedadec001eac68810a71c8d7668d1d5.jpg","route_question":"What happens on the free demo with Vlad, and how do I book it?","bullets":["A draft agent built on your own site","Live answers to your customers' real questions","Plan, setup and cost for your business","How it talks to people and their AI agents"],"questionnaire":[{"id":"full_name","label":"Your name","type":"text","required":true},{"id":"linkedin","label":"Your LinkedIn profile (optional)","type":"text"},{"id":"agent_tasks","label":"What should the agent do first?","type":"multi","options":["Answer visitors' questions","Book calls and demos","Capture leads","Take payments","Support customers","Talk to AI assistants"]},{"id":"team_size","label":"How big is your team?","type":"single","options":["Just me","2–10","11–50","51–200","200+"]},{"id":"website","label":"Your website","type":"text"}],"card":{"i18n":{"ru":{"policy":"Перенести или отменить можно в любой момент по ссылке из письма-приглашения.","details":["Видеозвонок на 30 минут на русском или английском. Пара коротких вопросов, выбор времени, приглашение придёт на почту.","Придём с черновиком агента на вашем сайте и при вас зададим ему настоящие вопросы ваших клиентов.","Потом обсудим, как внедрить его в ваш бизнес и как лучше обучить агента.","Уйдёте с пониманием, что он будет отвечать, какой тариф подходит и нужна ли помощь с настройкой."],"headline":"Агент, собранный на вашем сайте","host_bio":"Основатель Tobira. До этого основал иммиграционную tech-компанию, которая выросла до десятков тысяч клиентов, и вышел из неё. Выпускник Startup Battlefield 200. 12 лет программ инноваций и цифровой трансформации с глобальными компаниями: PwC, Coca-Cola HBC, Unilever, PepsiCo, Philip Morris International, IKEA, Deloitte. Живёт в Португалии (Порту и Лиссабон).","cta_label":"Записаться на демо","highlight":"Бесплатно. Без карты и обязательств.","host_role":"Основатель Tobira"}},"headline":"See an agent built on your own site, live in 30 minutes","highlight":"Free. No card, no commitment.","host_role":"Founder of Tobira","host_bio":"Founder of Tobira. Previously founded an immigration tech company that grew to tens of thousands of clients, and exited it. Startup Battlefield 200 alumni. 12 years of innovation and digital transformation programs with global companies such as PwC, Coca-Cola HBC, Unilever, PepsiCo, Philip Morris International, IKEA and Deloitte. Based in Portugal (Porto and Lisbon).","policy":"Reschedule or cancel any time from the link in your invite email.","cta_label":"Choose a time","details":["Answer a few quick questions and pick a time. The invite arrives by email.","We come with a draft agent built on your site and ask it your customers' real questions, live.","Together we map the launch: what it should answer, how to train it and which plan fits.","You leave with a clear next step: start free on your own, or let us set it up for you."]},"booking":{"duration_min":30,"host_name":"Vlad Shipilov","host_photo_url":"https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18zQjdWNTVYN2t2MXNlbmRvUmZIVkJVNldtbjgifQ"},"answers_schema":{"type":"object","additionalProperties":false,"properties":{"full_name":{"type":"string","maxLength":240,"minLength":1},"linkedin":{"type":"string","maxLength":240},"agent_tasks":{"type":"array","items":{"type":"string","enum":["Answer visitors' questions","Book calls and demos","Capture leads","Take payments","Support customers","Talk to AI assistants"]},"minItems":1,"uniqueItems":true},"team_size":{"type":"string","enum":["Just me","2–10","11–50","51–200","200+"]},"website":{"type":"string","maxLength":240}},"required":["full_name"]}},{"id":"ai-advisory-60","name":"AI consultation with Vlad · 60 min","price":300,"currency":"USD","description":"For founders and team leads who want AI to change real work, not sit in a pilot. We take one real problem from your business and leave with a plan you can start on the next day.","category":"Consultation","image_url":"https://tobira.ai/api/v1/agents/tobira-ai/widget-image/8e0d2ce1e993505a3a64e87c354832b1c827a520d52ddc4b6a203ba6ccba5f80.jpg","route_question":"What does the AI consultation with Vlad cover, and is it right for us?","bullets":["Where AI pays off first in your business","A first experiment and the metric to watch","How to get your team to actually use it","For startups: product, launch and AI strategy"],"questionnaire":[{"id":"full_name","label":"Your name","type":"text","required":true},{"id":"linkedin","label":"Your LinkedIn profile (optional)","type":"text"},{"id":"goal","label":"What do you want from the session?","type":"single","options":["Find where AI pays off first","Get my team using AI","Plan a pilot or rollout","Review an AI project we run","Startup product or strategy","Something else"]},{"id":"company_size","label":"Company size","type":"single","options":["Startup, under 10","10–50","51–250","251–1,000","1,000+"]},{"id":"company","label":"Company or website","type":"text"}],"card":{"headline":"Turn AI into working processes, one real problem at a time","highlight":"Useful on its own, whether or not you ever use Tobira","host_role":"AI adoption advisor · Founder of Tobira","host_bio":"Founder of Tobira. Previously founded an immigration tech company that grew to tens of thousands of clients, and exited it. Startup Battlefield 200 alumni. 12 years of innovation and digital transformation programs with global companies such as PwC, Coca-Cola HBC, Unilever, PepsiCo, Philip Morris International, IKEA and Deloitte. Based in Portugal (Porto and Lisbon).","policy":"Free cancellation and a full refund up to 24 hours before the session. Later than that, you can reschedule once, without a refund.","cta_label":"Choose a time","details":["A 60-minute video call in English or Russian. Answer three short questions, pick a time and pay securely. The invite arrives by email.","We take one real problem from your business and leave with a plan: what to try first, how to measure it and how to bring people along.","Within 1 working day you get a short written summary with next steps.","If a bigger project makes sense, such as a team program or a pilot, we scope it in writing after the call."]},"booking":{"duration_min":60,"host_name":"Vlad Shipilov","host_photo_url":"https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18zQjdWNTVYN2t2MXNlbmRvUmZIVkJVNldtbjgifQ"},"answers_schema":{"type":"object","additionalProperties":false,"properties":{"full_name":{"type":"string","maxLength":240,"minLength":1},"linkedin":{"type":"string","maxLength":240},"goal":{"type":"string","enum":["Find where AI pays off first","Get my team using AI","Plan a pilot or rollout","Review an AI project we run","Startup product or strategy","Something else"]},"company_size":{"type":"string","enum":["Startup, under 10","10–50","51–250","251–1,000","1,000+"]},"company":{"type":"string","maxLength":240}},"required":["full_name"]}}],"payment_pending_requires_checkout_url":true,"payment_is_human_action":true}}