{ "openapi": "3.1.0", "info": { "title": "MonCha API", "version": "1.0.1", "description": "Public REST API for MonCha — AI support agents with chat + voice in the languages Asia speaks. Authenticate with a scoped API token (create one in Dashboard → API & Agents): `Authorization: Bearer mgpt_…`. Requests require live API access on an active Growth trial, eligible paid Growth/Scale plan, or API-enabled enterprise contract. This workspace API is separate from Enterprise Vendor API." }, "servers": [ { "url": "https://api.dev-moncha.com/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from Dashboard → API (mgpt_…)" } }, "schemas": { "CreatedBot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "language": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "language", "created_at" ] }, "Conversation": { "type": "object", "properties": { "session_id": { "type": "string" }, "message_count": { "type": "integer" }, "first_at": { "type": "string", "format": "date-time" }, "last_at": { "type": "string", "format": "date-time" }, "preview": { "type": [ "string", "null" ] }, "channel": { "type": "string" } } }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "feedback": { "type": [ "string", "null" ], "enum": [ "positive", "negative", null ] }, "source_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "channel": { "type": "string" }, "provider_message_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "external_user_id": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "intent_category": { "type": [ "string", "null" ] }, "intent_summary": { "type": [ "string", "null" ] }, "score": { "type": "integer" }, "score_band": { "type": "string", "enum": [ "hot", "warm", "cold" ] }, "sentiment": { "type": [ "string", "null" ] }, "qualification": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "new", "contacted", "qualified", "won", "lost" ] }, "captured_via": { "type": "string", "enum": [ "conversational", "form", "inferred" ] }, "confidence": { "type": [ "number", "null" ] }, "notified_at": { "type": [ "string", "null" ], "format": "date-time" }, "asked_contact_at": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Analytics": { "type": "object", "properties": { "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "user_messages": { "type": "integer" }, "assistant_messages": { "type": "integer" } } } }, "top_questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "times": { "type": "integer" } } } }, "unanswered": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "rate": { "type": "number", "description": "Percentage from 0 to 100, rounded to one decimal place." } } }, "feedback": { "type": "object", "properties": { "positive": { "type": "integer" }, "negative": { "type": "integer" } } }, "sessions": { "type": "object", "properties": { "total": { "type": "integer" }, "avg_messages": { "type": "number" } } } }, "required": [ "daily", "top_questions", "unanswered", "feedback", "sessions" ] }, "Booking": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "requested_slot": { "type": [ "string", "null" ], "format": "date-time" }, "country": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] }, "custom_fields": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "cancelled" ] }, "rejection_comment": { "type": [ "string", "null" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "additionalProperties": true, "description": "Structured validation error; inspect its issues." } } }, "Bot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 30 }, "slot_kind": { "type": "string", "enum": [ "plan", "addon", "vendor" ] }, "language": { "type": "string", "example": "en-IN" }, "created_at": { "type": "string", "format": "date-time" } } }, "KBDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "source_type": { "type": "string", "enum": [ "url", "file", "qa", "snippet" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ] }, "chunk_count": { "type": "integer" }, "chatbot_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retry_after": { "type": "integer" }, "suggested_name": { "type": "string" }, "available_slots": { "type": "object", "additionalProperties": { "type": "integer" } } } } } }, "paths": { "/bots": { "get": { "summary": "List bots", "description": "Requires scope `bots:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Bot list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } } } } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } }, "post": { "summary": "Create a bot", "description": "Requires scope `bots:write`. Bot-restricted tokens cannot create bots. Enterprise workspaces must supply `enterprise_plan_tier` and have an available slot in that tier.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30 }, "language": { "type": "string", "example": "en-IN" }, "enterprise_plan_tier": { "type": "string", "enum": [ "starter", "growth", "scale" ], "description": "Required for enterprise workspaces" } } } } } }, "responses": { "201": { "description": "Created bot", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedBot" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bot name is already used; inspect suggested_name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/kb": { "get": { "summary": "List knowledge-base documents", "description": "Requires scope `kb:read`. Filter with `?chatbotId=`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chatbotId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KBDocument" } } } } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/kb/ingest": { "post": { "summary": "Add knowledge (URL or raw text)", "description": "Requires scope `kb:write`. Queued for crawling/embedding; poll GET /kb for status.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "anyOf": [ { "required": [ "url" ] }, { "required": [ "text" ], "properties": { "text": { "minLength": 1 } } } ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "url": { "type": "string", "format": "uri" }, "text": { "type": "string", "maxLength": 200000 }, "chatbotId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/chat": { "post": { "summary": "Chat with a bot (streaming)", "description": "Requires scope `chat:invoke`. Returns a Server-Sent Events stream of OpenAI-style chunks (`data: {\"choices\":[{\"delta\":{\"content\":\"…\"}}]}`). Counts toward your monthly message quota.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "chatbotId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "maxLength": 120, "description": "Stable id groups turns into one conversation" }, "language": { "type": "string", "example": "ja-JP", "description": "Reply language. Any supported code, e.g. en-IN, ja-JP, ko-KR, zh-CN, ms-MY, id-ID, th-TH, vi-VN, fil-PH, ar-AE, hi-IN, ta-IN, sw-KE, ha-NG, yo-NG. Omit to use the bot’s default; the bot still matches the language the user writes in." } } } } } }, "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE data frames containing JSON chunks; consume incrementally until the stream closes." }, "example": "data: {\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\n" } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/conversations": { "get": { "summary": "List conversations", "description": "Requires scope `conversations:read`. Supports `?q=` search, `?limit=`, `?chatbotId=`. Default limit 50, maximum 200; no page or cursor parameter.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "chatbotId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/conversations/{sessionId}": { "get": { "summary": "Get a conversation transcript", "description": "Requires scope `conversations:read`. Returns an array; a missing session can return an empty array. Restricted tokens may receive 403 for inaccessible sessions.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Messages in the session", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/leads": { "get": { "summary": "List leads", "description": "Requires scope `leads:read`. At most 500 intent-scored leads, newest first; no cursor pagination; optional `?chatbotId=`. Each lead has score/band, an AI summary, contact details, qualification, and `external_user_id` when the visitor was signed in (MonCha.identify).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chatbotId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lead list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/analytics": { "get": { "summary": "Analytics summary (30 days)", "description": "Requires scope `analytics:read`. Daily volumes, top questions, unanswered rate, feedback, sessions.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chatbotId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Analytics summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Analytics" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/bookings": { "get": { "summary": "List bookings", "description": "Requires scope `bookings:read`. Appointment requests newest first. Filter with `?status=pending|confirmed|rejected|cancelled`, `?chatbotId=`, `?limit=`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "cancelled" ] } }, { "name": "chatbotId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } } ], "responses": { "200": { "description": "Booking list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/bookings/{id}": { "get": { "summary": "Get a booking", "description": "Requires scope `bookings:read`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } }, "patch": { "summary": "Update a booking", "description": "Requires scope `bookings:write`. `action` is `confirm`, `reject`, `reschedule`, or `cancel`. Confirm/reject apply to pending requests. Reschedule and cancel apply to pending or confirmed bookings and email the visitor. Reschedule requires `requestedSlot`. Optional `cancelComment` / `rejectionComment` is included in the visitor email.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "allOf": [ { "if": { "properties": { "action": { "const": "reschedule" } } }, "then": { "required": [ "requestedSlot" ] } } ], "properties": { "action": { "type": "string", "enum": [ "confirm", "reject", "reschedule", "cancel" ] }, "requestedSlot": { "type": "string", "format": "date-time" }, "rejectionComment": { "type": "string", "maxLength": 500 }, "cancelComment": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Updated booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input or operation requirements. Validation can return a structured error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "API/live service unavailable (api_locked), plan capacity or quota exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or bot access is missing, or enterprise tier capacity is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or account not found in the accessible context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slot taken, already decided or booking no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } } } }