Welcome to Zavu!
We're excited to have you on board.
", "replyTo": "support@example.com" } }, "email_attachment": { "summary": "Email with attachments", "value": { "to": "user@example.com", "channel": "email", "subject": "Your invoice", "text": "Please find your invoice attached.", "attachments": [ { "filename": "invoice.pdf", "content": "JVBERi0xLjQK...", "content_type": "application/pdf" } ] } }, "email_inline_image": { "summary": "Email with inline image", "value": { "to": "user@example.com", "channel": "email", "subject": "Your report", "text": "See your report below.", "htmlBody": "Report
Details above.
", "attachments": [ { "filename": "chart.png", "path": "https://example.com/chart.png", "content_type": "image/png", "content_id": "chart" } ] } } } } } }, "responses": { "202": { "description": "Message accepted for delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Invalid request or WhatsApp 24h window not open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "window_closed": { "summary": "WhatsApp window closed", "value": { "code": "whatsapp_window_closed", "message": "WhatsApp 24-hour window is not open. Use a template message or wait for user to message first." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance. Email is billed from your prepaid balance in 1,000-message blocks; SMS and voice are billed per message. When the balance cannot cover the send, the message is rejected until you add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "insufficient_balance", "message": "Insufficient balance to send email. Add funds from the dashboard to resume." } } } }, "403": { "description": "Message blocked due to URL restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "url_not_verified": { "summary": "URL not verified", "value": { "code": "url_not_verified", "message": "Message blocked: Contains unverified URLs. Submit URLs for verification via the /v1/urls endpoint.", "details": { "urls": [ "https://example.com" ], "submissionEndpoint": "/v1/urls" } } }, "url_shortener_blocked": { "summary": "URL shortener blocked", "value": { "code": "url_shortener_blocked", "message": "Message blocked: URL shorteners are not allowed. Please use the full destination URL.", "details": { "blockedUrls": [ "https://bit.ly/abc123" ], "reason": "url_shorteners_hidden_destination" } } } } } } }, "404": { "description": "Template or sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict (message already sent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List messages", "description": "List messages previously sent by this project.", "operationId": "listMessages", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status. Not all stored statuses are filterable.", "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "failed", "received" ] } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "description": "Filter by delivery channel.", "schema": { "type": "string", "enum": [ "sms", "sms_oneway", "whatsapp", "email", "telegram", "instagram", "messenger", "voice" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{messageId}": { "get": { "summary": "Get message by ID", "operationId": "getMessage", "parameters": [ { "$ref": "#/components/parameters/MessageIdParam" } ], "responses": { "200": { "description": "Message details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{messageId}/reactions": { "post": { "summary": "Send reaction to message", "description": "Send an emoji reaction to an existing WhatsApp message. Reactions are only supported for WhatsApp messages.", "operationId": "sendReaction", "parameters": [ { "$ref": "#/components/parameters/MessageIdParam" }, { "$ref": "#/components/parameters/SenderHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactionRequest" }, "example": { "emoji": "👍" } } } }, "responses": { "202": { "description": "Reaction accepted for delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Invalid request or message is not from WhatsApp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_whatsapp": { "summary": "Not a WhatsApp message", "value": { "code": "bad_request", "message": "Reactions are only supported for WhatsApp messages" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{messageId}/typing": { "post": { "summary": "Show typing indicator", "description": "Mark an inbound WhatsApp message as read and display a typing indicator to the user while you prepare a response. The indicator is automatically dismissed when you send a reply, or after 25 seconds — whichever comes first. Only valid for inbound WhatsApp messages. Use this when a reply will take more than a couple of seconds (LLM agent, tool call, lookup) to improve the recipient's experience.", "operationId": "showTypingIndicator", "parameters": [ { "$ref": "#/components/parameters/MessageIdParam" }, { "$ref": "#/components/parameters/SenderHeader" } ], "responses": { "202": { "description": "Typing indicator displayed and message marked as read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request — message is not WhatsApp, not inbound, or has no provider message ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_whatsapp": { "summary": "Not a WhatsApp message", "value": { "code": "bad_request", "message": "Typing indicators are only supported for WhatsApp messages" } }, "not_inbound": { "summary": "Message is not inbound", "value": { "code": "bad_request", "message": "Typing indicators can only be sent in response to inbound messages" } }, "no_provider_id": { "summary": "Missing provider message ID", "value": { "code": "bad_request", "message": "Cannot send typing indicator: no provider message ID available" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{messageId}/attachments": { "get": { "summary": "List message attachments", "description": "List the stored file attachments for an email message and get a short-lived signed `downloadUrl` for each. Works for both inbound emails (received via `message.inbound`) and outbound emails you sent with attachments. Messages without stored attachments (including SMS, WhatsApp, and other channels) return an empty list. Each `downloadUrl` is generated fresh per request and expires — fetch the file promptly and do not cache the URL.", "operationId": "listMessageAttachments", "parameters": [ { "$ref": "#/components/parameters/MessageIdParam" } ], "responses": { "200": { "description": "List of attachments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageAttachmentsResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/templates": { "get": { "summary": "List templates", "description": "List WhatsApp message templates for this project.", "operationId": "listTemplates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create template", "description": "Create a WhatsApp message template. Note: Templates must be approved by Meta before use.", "operationId": "createTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateRequest" }, "example": { "name": "order_confirmation", "language": "en", "body": "Hi {{1}}, your order {{2}} has been confirmed and will ship within 24 hours.", "whatsappCategory": "UTILITY", "variables": [ "customer_name", "order_id" ] } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/templates/{templateId}": { "get": { "summary": "Get template", "operationId": "getTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdParam" } ], "responses": { "200": { "description": "Template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete template", "operationId": "deleteTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdParam" } ], "responses": { "204": { "description": "Template deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/templates/{templateId}/submit": { "post": { "summary": "Submit template for approval", "description": "Submit a WhatsApp template to Meta for approval. The template must be in draft status and associated with a sender that has a WhatsApp Business Account configured.", "operationId": "submitTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "senderId" ], "properties": { "senderId": { "type": "string", "description": "The sender ID with the WhatsApp Business Account to submit the template to." }, "category": { "$ref": "#/components/schemas/WhatsAppCategory", "description": "Template category. If not provided, uses the category set on the template." } } }, "example": { "senderId": "sender_abc123", "category": "UTILITY" } } } }, "responses": { "202": { "description": "Template submitted for approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid request or template not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_draft": { "summary": "Template not in draft status", "value": { "code": "bad_request", "message": "Template is already pending approval or approved" } }, "no_waba": { "summary": "Sender has no WABA", "value": { "code": "bad_request", "message": "Sender does not have a WhatsApp Business Account configured" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template or sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders": { "get": { "summary": "List senders", "operationId": "listSenders", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of sender profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Sender" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create sender", "operationId": "createSender", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderCreateRequest" } } } }, "responses": { "201": { "description": "Sender created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "400": { "description": "Invalid sender.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}": { "get": { "summary": "Get sender", "operationId": "getSender", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "Sender details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update sender", "operationId": "updateSender", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderUpdateRequest" } } } }, "responses": { "200": { "description": "Sender updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "400": { "description": "Invalid update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete sender", "operationId": "deleteSender", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "204": { "description": "Sender deleted." }, "400": { "description": "Cannot delete default sender.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/webhook/secret": { "post": { "summary": "Regenerate webhook secret", "description": "Regenerate the webhook secret for a sender. The old secret will be invalidated immediately.", "operationId": "regenerateSenderWebhookSecret", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "New webhook secret generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretResponse" } } } }, "400": { "description": "Sender has no webhook configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/profile": { "get": { "summary": "Get WhatsApp Business profile", "description": "Get the WhatsApp Business profile for a sender. The sender must have a WhatsApp Business Account connected.", "operationId": "getSenderProfile", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "WhatsApp Business profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppBusinessProfileResponse" } } } }, "400": { "description": "Sender does not have a WhatsApp Business Account connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update WhatsApp Business profile", "description": "Update the WhatsApp Business profile for a sender. The sender must have a WhatsApp Business Account connected.", "operationId": "updateSenderProfile", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppBusinessProfileUpdateRequest" }, "example": { "about": "Succulent specialists!", "description": "We specialize in providing high-quality succulents.", "email": "contact@example.com", "websites": [ "https://www.example.com" ], "vertical": "RETAIL" } } } }, "responses": { "200": { "description": "Profile updated successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "profile" ], "properties": { "success": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/WhatsAppBusinessProfile" } } } } } }, "400": { "description": "Invalid request or sender does not have a WhatsApp Business Account connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/profile/picture": { "post": { "summary": "Upload WhatsApp Business profile picture", "description": "Upload a new profile picture for the WhatsApp Business profile. The image will be uploaded to Meta and set as the profile picture.", "operationId": "uploadSenderProfilePicture", "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppBusinessProfilePictureRequest" }, "example": { "imageUrl": "https://example.com/profile.jpg", "mimeType": "image/jpeg" } } } }, "responses": { "200": { "description": "Profile picture uploaded successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "profile" ], "properties": { "success": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/WhatsAppBusinessProfile" } } } } } }, "400": { "description": "Invalid request or sender does not have a WhatsApp Business Account connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/whatsapp-sync": { "get": { "summary": "Get WhatsApp sync status", "description": "Get the current sync status for a sender's WhatsApp coexistence account. Only available for senders connected in coexistence mode (WhatsApp Business App + Cloud API).", "operationId": "getWhatsAppSyncStatus", "tags": [ "WhatsApp Sync" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "Sync status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppSyncStatusResponse" }, "example": { "sync": { "isCoexistence": true, "status": "active", "history": { "status": "completed", "canSync": false, "requestedAt": "2024-01-15T10:00:00Z", "completedAt": "2024-01-15T10:05:00Z" }, "contacts": { "status": "not_requested", "canSync": true, "requestedAt": null } } } } } }, "400": { "description": "Sender does not have a WhatsApp Business Account connected or is not in coexistence mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_waba": { "summary": "No WABA connected", "value": { "code": "bad_request", "message": "Sender does not have a WhatsApp Business Account connected" } }, "not_coexistence": { "summary": "Not coexistence mode", "value": { "code": "bad_request", "message": "Sync is only available for coexistence accounts" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/whatsapp-sync/history": { "post": { "summary": "Start history sync", "description": "Initiate message history sync from the WhatsApp Business App. This sends a request to the account owner to approve sharing their conversation history. Only available for coexistence accounts with active status.", "operationId": "startWhatsAppHistorySync", "tags": [ "WhatsApp Sync" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "202": { "description": "History sync initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppSyncStartResponse" }, "example": { "message": "History sync initiated", "sync": { "isCoexistence": true, "status": "active", "history": { "status": "pending", "canSync": false, "requestedAt": "2024-01-15T10:00:00Z", "completedAt": null }, "contacts": { "status": "not_requested", "canSync": true, "requestedAt": null } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_waba": { "summary": "No WABA connected", "value": { "code": "bad_request", "message": "Sender does not have a WhatsApp Business Account connected" } }, "not_coexistence": { "summary": "Not coexistence mode", "value": { "code": "bad_request", "message": "History sync is only available for coexistence accounts" } }, "not_active": { "summary": "Account not active", "value": { "code": "bad_request", "message": "WhatsApp account is not active" } }, "in_progress": { "summary": "Sync in progress", "value": { "code": "bad_request", "message": "History sync is already in progress" } }, "rate_limit": { "summary": "Rate limit", "value": { "code": "bad_request", "message": "Sync limit reached. Please wait 24 hours before trying again." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/whatsapp-sync/contacts": { "post": { "summary": "Start contacts sync", "description": "Initiate contact names sync from the WhatsApp Business App. This imports contact names stored in the app to Zavu. Only available for coexistence accounts with active status.", "operationId": "startWhatsAppContactsSync", "tags": [ "WhatsApp Sync" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "202": { "description": "Contacts sync initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppSyncStartResponse" }, "example": { "message": "Contacts sync initiated", "sync": { "isCoexistence": true, "status": "active", "history": { "status": "completed", "canSync": false, "requestedAt": "2024-01-15T10:00:00Z", "completedAt": "2024-01-15T10:05:00Z" }, "contacts": { "status": "pending", "canSync": false, "requestedAt": "2024-01-15T11:00:00Z" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_waba": { "summary": "No WABA connected", "value": { "code": "bad_request", "message": "Sender does not have a WhatsApp Business Account connected" } }, "not_coexistence": { "summary": "Not coexistence mode", "value": { "code": "bad_request", "message": "Contacts sync is only available for coexistence accounts" } }, "not_active": { "summary": "Account not active", "value": { "code": "bad_request", "message": "WhatsApp account is not active" } }, "in_progress": { "summary": "Sync in progress", "value": { "code": "bad_request", "message": "Contacts sync is already in progress" } }, "rate_limit": { "summary": "Rate limit", "value": { "code": "bad_request", "message": "Sync limit reached. Please wait 24 hours before trying again." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts": { "get": { "summary": "List contacts", "description": "List contacts with their communication channels.", "operationId": "listContacts", "parameters": [ { "name": "phoneNumber", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create contact", "description": "Create a new contact with one or more communication channels.", "operationId": "createContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequest" }, "examples": { "phone_only": { "summary": "Contact with phone only", "value": { "displayName": "John Doe", "channels": [ { "channel": "sms", "identifier": "+14155551234", "isPrimary": true } ] } }, "multi_channel": { "summary": "Contact with multiple channels", "value": { "displayName": "John Doe", "channels": [ { "channel": "sms", "identifier": "+14155551234", "isPrimary": true }, { "channel": "whatsapp", "identifier": "+14155551234", "isPrimary": true }, { "channel": "email", "identifier": "john@example.com", "isPrimary": true } ], "metadata": { "source": "import" } } }, "email_only": { "summary": "Contact with email only", "value": { "displayName": "Jane Smith", "channels": [ { "channel": "email", "identifier": "jane@example.com", "isPrimary": true } ] } } } } } }, "responses": { "201": { "description": "Contact created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "duplicate_identifier": { "summary": "Duplicate identifier", "value": { "code": "bad_request", "message": "This sms identifier is already associated with another contact" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}": { "get": { "summary": "Get contact", "operationId": "getContact", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "responses": { "200": { "description": "Contact details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update contact", "operationId": "updateContact", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequest" } } } }, "responses": { "200": { "description": "Contact updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete contact", "description": "Permanently delete a contact and its communication channels. Implements right-to-erasure obligations under GDPR Art. 17, Ley 19.628 (Chile) Art. 12, CCPA § 1798.105, and LGPD Art. 18.VI. The contact, its channels, and any associated agent flow sessions and conversation threads are removed. Past message records and broadcast delivery logs are retained for billing/audit but no longer reference the deleted contact.", "operationId": "deleteContact", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "responses": { "204": { "description": "Contact deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/phone/{phoneNumber}": { "get": { "summary": "Get contact by phone number", "operationId": "getContactByPhone", "parameters": [ { "name": "phoneNumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "E.164 phone number." } ], "responses": { "200": { "description": "Contact details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}/channels": { "post": { "summary": "Add channel to contact", "description": "Add a new communication channel to an existing contact.", "operationId": "addContactChannel", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelRequest" }, "example": { "channel": "email", "identifier": "john.work@company.com", "label": "work" } } } }, "responses": { "201": { "description": "Channel added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactChannelResponse" } } } }, "400": { "description": "Invalid request or duplicate identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}/channels/{channelId}": { "patch": { "summary": "Update channel", "description": "Update a contact's channel properties.", "operationId": "updateContactChannel", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelRequest" } } } }, "responses": { "200": { "description": "Channel updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactChannelResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact or channel not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Remove channel from contact", "description": "Remove a communication channel from a contact. Cannot remove the last channel.", "operationId": "removeContactChannel", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel ID." } ], "responses": { "204": { "description": "Channel removed." }, "400": { "description": "Cannot remove the last channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact or channel not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}/channels/{channelId}/primary": { "post": { "summary": "Set channel as primary", "description": "Set a channel as the primary channel for its type.", "operationId": "setPrimaryChannel", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel ID." } ], "responses": { "200": { "description": "Channel set as primary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactChannelResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact or channel not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}/merge": { "post": { "summary": "Merge contacts", "description": "Merge a source contact into this contact. All channels from the source contact will be moved to the target contact, and the source contact will be marked as merged.", "operationId": "mergeContacts", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeContactsRequest" }, "example": { "sourceContactId": "jx7xyz789" } } } }, "responses": { "200": { "description": "Contacts merged. Returns the updated target contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request (e.g., cannot merge contact with itself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Target or source contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contactId}/merge-suggestion": { "delete": { "summary": "Dismiss merge suggestion", "description": "Dismiss the merge suggestion for a contact.", "operationId": "dismissMergeSuggestion", "parameters": [ { "$ref": "#/components/parameters/ContactIdParam" } ], "responses": { "204": { "description": "Merge suggestion dismissed." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/conversations": { "get": { "summary": "List conversations", "description": "List inbox threads, most recently active first. A conversation groups every message with one contact across channels, which is what you need to build an inbox: `GET /v1/messages` returns a flat log with no thread to hang it on.\n\nUse `senderId` to scope the list to a single number, and `channel` to keep only threads that have carried that channel.", "operationId": "listConversations", "tags": [ "Conversations" ], "parameters": [ { "name": "channel", "in": "query", "description": "Keep only threads that have carried this channel.", "schema": { "type": "string", "enum": [ "sms", "sms_oneway", "whatsapp", "email", "telegram", "instagram", "messenger", "voice" ] } }, { "name": "senderId", "in": "query", "description": "Keep only threads last handled by this sender.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `nextCursor`. Do not construct it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of conversations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/conversations/{conversationId}": { "get": { "summary": "Get conversation", "operationId": "getConversation", "tags": [ "Conversations" ], "parameters": [ { "$ref": "#/components/parameters/ConversationIdParam" } ], "responses": { "200": { "description": "Conversation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/conversations/{conversationId}/messages": { "get": { "summary": "List conversation messages", "description": "Messages in this thread, newest first, across every channel it has carried. Reply with `POST /v1/messages`, passing the conversation's `senderId` as the `Zavu-Sender` header so the answer leaves from the number the contact already knows.", "operationId": "listConversationMessages", "tags": [ "Conversations" ], "parameters": [ { "$ref": "#/components/parameters/ConversationIdParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `nextCursor`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/conversations/{conversationId}/read": { "post": { "summary": "Mark conversation as read", "description": "Reset the thread's `unreadCount` to zero. Marks the thread read in your own inbox only: it does not send a read receipt to the contact.", "operationId": "markConversationRead", "tags": [ "Conversations" ], "parameters": [ { "$ref": "#/components/parameters/ConversationIdParam" } ], "responses": { "200": { "description": "Conversation marked as read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/introspect/phone": { "post": { "summary": "Introspect phone number", "description": "Validate a phone number and check if a WhatsApp conversation window is open.", "operationId": "introspectPhone", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneIntrospectionRequest" } } } }, "responses": { "200": { "description": "Phone number introspection result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneIntrospectionResponse" } } } }, "400": { "description": "Invalid phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/introspect/email": { "post": { "summary": "Validate email addresses", "description": "Heuristic email validation to run before sending: catches invalid syntax, dead domains (no MX/A records), disposable inboxes, role-based addresses (info@, contacto@, sales@), and addresses already on your project's suppression list. Use it to clean a list before a broadcast and keep your bounce rate low.\n\nNo mailbox-level (SMTP) probe is performed, so a `deliverable` verdict is not a delivery guarantee — it means no negative signal was found. Treat `risky` addresses with care and drop `undeliverable` ones.\n\nAccepts a single `email` or an `emails` batch (max 100 per request).", "operationId": "introspectEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailIntrospectionRequest" }, "examples": { "single": { "summary": "Validate one address", "value": { "email": "maria@example.com" } }, "batch": { "summary": "Validate a list", "value": { "emails": [ "maria@example.com", "info@deaddomain.example", "not-an-email" ] } } } } } }, "responses": { "200": { "description": "Validation results, one per submitted address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailIntrospectionResponse" }, "example": { "results": [ { "email": "maria@example.com", "normalized": "maria@example.com", "domain": "example.com", "verdict": "deliverable", "reasons": [] }, { "email": "info@deaddomain.example", "normalized": "info@deaddomain.example", "domain": "deaddomain.example", "verdict": "undeliverable", "reasons": [ "domain_not_found", "role_address" ] }, { "email": "not-an-email", "normalized": null, "domain": null, "verdict": "undeliverable", "reasons": [ "invalid_syntax" ] } ], "summary": { "total": 3, "deliverable": 1, "risky": 0, "undeliverable": 2 } } } } }, "400": { "description": "Invalid request body (no addresses, or more than 100).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts": { "post": { "summary": "Create broadcast", "description": "Create a new broadcast campaign. Add contacts after creation, then send.", "operationId": "createBroadcast", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastCreateRequest" }, "examples": { "sms": { "summary": "SMS broadcast", "value": { "name": "Black Friday Sale", "channel": "sms", "text": "Hi {{name}}, check out our Black Friday deals! Use code FRIDAY20 for 20% off." } }, "whatsapp_template": { "summary": "WhatsApp template broadcast", "value": { "name": "Order Confirmation Campaign", "channel": "whatsapp", "messageType": "template", "content": { "templateId": "tmpl_abc123" } } }, "telegram": { "summary": "Telegram broadcast", "value": { "name": "Product Announcement", "channel": "telegram", "text": "Hi {{name}}, check out our new product launch!" } }, "email": { "summary": "Email broadcast", "value": { "name": "Newsletter", "channel": "email", "emailSubject": "Your Weekly Update", "text": "Hi {{name}}, here's what's new this week..." } } } } } }, "responses": { "201": { "description": "Broadcast created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict (broadcast already exists).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List broadcasts", "description": "List broadcasts for this project.", "operationId": "listBroadcasts", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/BroadcastStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of broadcasts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}": { "get": { "summary": "Get broadcast", "operationId": "getBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "200": { "description": "Broadcast details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update broadcast", "description": "Update a broadcast in draft status.", "operationId": "updateBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpdateRequest" } } } }, "responses": { "200": { "description": "Broadcast updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Invalid request or broadcast not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete broadcast", "description": "Delete a broadcast in draft status.", "operationId": "deleteBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "204": { "description": "Broadcast deleted." }, "400": { "description": "Broadcast not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/contacts": { "post": { "summary": "Add contacts to broadcast", "description": "Add contacts to a broadcast in batch. Maximum 1000 contacts per request.", "operationId": "addBroadcastContacts", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastContactsAddRequest" }, "example": { "contacts": [ { "recipient": "+14155551234", "templateVariables": { "name": "John", "order_id": "ORD-001" } }, { "recipient": "+14155555678", "templateVariables": { "name": "Jane", "order_id": "ORD-002" } } ] } } } }, "responses": { "201": { "description": "Contacts added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastContactsAddResponse" } } } }, "400": { "description": "Invalid request or broadcast not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List broadcast contacts", "description": "List contacts in a broadcast with optional status filter.", "operationId": "listBroadcastContacts", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/BroadcastContactStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of broadcast contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastContact" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/contacts/{contactId}": { "delete": { "summary": "Remove contact from broadcast", "description": "Remove a contact from a broadcast in draft status.", "operationId": "removeBroadcastContact", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" }, { "$ref": "#/components/parameters/BroadcastContactIdParam" } ], "responses": { "204": { "description": "Contact removed." }, "400": { "description": "Broadcast not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast or contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/send": { "post": { "summary": "Send broadcast", "description": "Start sending the broadcast immediately or schedule for later.\n\n**Verification is required to send, and there are two of them.** The team must have completed both identity verification (KYC) and business verification (KYB); passing one is not enough. Drafts can be created, edited and kept without either. Every send path — dashboard, API and CLI alike — enforces both, returning `403` with code `kyc_required` or `kyb_required` for whichever is outstanding.\n\n**Review depends on the channel, and cannot be bypassed.** A draft is submitted to automated content review here; it does not go straight out. A WhatsApp broadcast built on a Meta-approved template skips review (Meta already vetted the content) and begins sending. An email broadcast sends as soon as the automated review passes. Every other channel moves to `pending_admin_review` and waits for a person. If the review rejects it, use PATCH to edit the content then call POST /retry-review.\n\nCalling this on a broadcast that is already `approved` or `scheduled` sends or reschedules it directly, since it has already been reviewed. Reserves the estimated cost from your balance.", "operationId": "sendBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastSendRequest" }, "examples": { "immediate": { "summary": "Send immediately", "value": {} }, "scheduled": { "summary": "Schedule for later", "value": { "scheduledAt": "2024-01-15T10:00:00Z" } } } } } }, "responses": { "202": { "description": "Broadcast started or scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Invalid request, no contacts, or broadcast not in valid status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "insufficient_balance", "message": "Insufficient balance. Available: $50.00", "details": { "totalBalance": 50, "reservedBalance": 25, "availableBalance": 25 } } } } }, "403": { "description": "Verification required. Sending needs both identity (KYC) and business (KYB) verification; the code says which one is missing. Drafts are unaffected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "kyc_required": { "summary": "Identity not verified", "value": { "code": "kyc_required", "message": "Verify your identity before sending broadcasts. Drafts can be created and edited without it.", "details": { "dashboardUrl": "/kyc" } } }, "kyb_required": { "summary": "Business not verified", "value": { "code": "kyb_required", "message": "Complete Business Verification before sending broadcasts. Drafts can be created and edited without it.", "details": { "dashboardUrl": "/compliance/verify" } } } } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/schedule": { "patch": { "summary": "Reschedule broadcast", "description": "Update the scheduled time for a broadcast. The broadcast must be in scheduled status.", "operationId": "rescheduleBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastRescheduleRequest" }, "example": { "scheduledAt": "2024-01-15T14:00:00Z" } } } }, "responses": { "200": { "description": "Broadcast rescheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Invalid request or broadcast not in scheduled status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/cancel": { "post": { "summary": "Cancel broadcast", "description": "Cancel a broadcast. Pending contacts will be skipped, but already queued messages may still be delivered.", "operationId": "cancelBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "200": { "description": "Broadcast cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Broadcast cannot be cancelled in current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/retry-review": { "post": { "summary": "Retry broadcast review", "description": "Resubmit a rejected broadcast for AI review after editing content. Maximum 3 review attempts allowed per broadcast.", "operationId": "retryBroadcastReview", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "200": { "description": "Review resubmitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Broadcast not in rejected status or max attempts reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_rejected": { "summary": "Broadcast not rejected", "value": { "code": "invalid_request", "message": "Only rejected broadcasts can retry review" } }, "max_attempts": { "summary": "Max attempts reached", "value": { "code": "invalid_request", "message": "Maximum review attempts reached. Request manual review instead." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/escalate": { "post": { "summary": "Escalate to manual review", "description": "Request manual review by the Zavu team for a rejected broadcast. Use this after automated review rejection if you believe the content is legitimate.", "operationId": "escalateBroadcast", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "200": { "description": "Escalation submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastResponse" } } } }, "400": { "description": "Broadcast not in rejected status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "invalid_request", "message": "Only rejected broadcasts can be escalated" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/broadcasts/{broadcastId}/progress": { "get": { "summary": "Get broadcast progress", "description": "Get real-time progress of a broadcast including delivery counts and estimated completion time.", "operationId": "getBroadcastProgress", "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "responses": { "200": { "description": "Broadcast progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastProgress" }, "example": { "broadcastId": "brd_abc123", "status": "sending", "total": 5000, "pending": 2500, "sending": 100, "delivered": 2350, "failed": 50, "skipped": 0, "percentComplete": 48, "estimatedCost": 75, "reservedAmount": 75, "actualCost": 35.25, "startedAt": "2024-01-15T10:30:00.000Z", "estimatedCompletionAt": "2024-01-15T10:45:00.000Z" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Broadcast not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/phone-numbers/requirements": { "get": { "summary": "Get regulatory requirements", "description": "Get regulatory requirements for purchasing phone numbers in a specific country. Some countries require additional documentation (addresses, identity documents) before phone numbers can be activated.", "operationId": "getPhoneNumberRequirements", "parameters": [ { "name": "countryCode", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "DE", "description": "Two-letter ISO country code." }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/PhoneNumberType" }, "description": "Type of phone number (local, mobile, tollFree)." } ], "responses": { "200": { "description": "List of requirements for the country/type combination.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Requirement" } } } }, "example": { "items": [ { "id": "req_123", "countryCode": "DE", "phoneNumberType": "local", "action": "ordering", "requirementTypes": [ { "id": "address_proof", "name": "Proof of Address", "description": "A document proving your address in Germany", "type": "document" } ] } ] } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/phone-numbers/available": { "get": { "summary": "Search available phone numbers", "description": "Search for available phone numbers to purchase by country and type.", "operationId": "searchAvailablePhoneNumbers", "parameters": [ { "name": "countryCode", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "US", "description": "Two-letter ISO country code." }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/PhoneNumberType" }, "description": "Type of phone number to search for." }, { "name": "contains", "in": "query", "schema": { "type": "string", "maxLength": 20 }, "description": "Search for numbers containing this string." }, { "name": "capabilities", "in": "query", "description": "Comma-separated capabilities the number must have: `sms`, `voice`, `mms`. Numbers missing any of them are dropped.", "schema": { "type": "string", "example": "voice,sms" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 }, "description": "Maximum number of results to return." } ], "responses": { "200": { "description": "List of available phone numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AvailablePhoneNumber" } } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/phone-numbers": { "post": { "summary": "Purchase a phone number", "description": "Purchase an available phone number. Requires a paid plan: the Free plan cannot purchase phone numbers and receives `402` with code `paid_plan_required`. Paid plans include the first US number at no charge.", "operationId": "purchasePhoneNumber", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberPurchaseRequest" }, "example": { "phoneNumber": "+15551234567", "name": "Primary Line" } } } }, "responses": { "201": { "description": "Phone number purchased successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "400": { "description": "Invalid request or phone number no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. Either the balance cannot cover the purchase (code `insufficient_balance`) or the team is on the Free plan (code `paid_plan_required`): buying phone numbers requires a paid plan, which includes the first US number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "Balance cannot cover the purchase", "value": { "code": "insufficient_balance", "message": "Insufficient balance. Required: $1.25. Please add funds to continue." } }, "paid_plan_required": { "summary": "Free plan cannot purchase numbers", "value": { "code": "paid_plan_required", "message": "Buying phone numbers requires a paid plan. Upgrade to Pro to get one US number included." } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List phone numbers", "description": "List all phone numbers owned by this project.", "operationId": "listPhoneNumbers", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PhoneNumberStatus" }, "description": "Filter by phone number status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor." } ], "responses": { "200": { "description": "List of phone numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OwnedPhoneNumber" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/phone-numbers/{phoneNumberId}": { "get": { "summary": "Get phone number", "description": "Get details of a specific phone number.", "operationId": "getPhoneNumber", "parameters": [ { "$ref": "#/components/parameters/PhoneNumberIdParam" } ], "responses": { "200": { "description": "Phone number details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update phone number", "description": "Update a phone number's name or sender assignment.", "operationId": "updatePhoneNumber", "parameters": [ { "$ref": "#/components/parameters/PhoneNumberIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberUpdateRequest" }, "examples": { "rename": { "summary": "Rename phone number", "value": { "name": "Support Line" } }, "assign": { "summary": "Assign to sender", "value": { "senderId": "sender_abc123" } }, "unassign": { "summary": "Unassign from sender", "value": { "senderId": null } } } } } }, "responses": { "200": { "description": "Phone number updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number or sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Release phone number", "description": "Release a phone number. The phone number must not be assigned to a sender.", "operationId": "releasePhoneNumber", "parameters": [ { "$ref": "#/components/parameters/PhoneNumberIdParam" } ], "responses": { "204": { "description": "Phone number released." }, "400": { "description": "Cannot release phone number assigned to a sender.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/invitations": { "post": { "summary": "Create invitation", "description": "Create a partner invitation link for a client to connect a Meta channel. The client opens the returned `url` and authorizes with Meta; the resulting sender is created in your project when they finish, and the invitation transitions to `completed`.\n\n`connectionType` picks the channel:\n- `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp Business Account.\n- `messenger`: the client picks a Facebook Page they administer; its Messenger inbox (including Marketplace chats) is routed to Zavu.\n\nOne invitation connects one channel — create one per channel to onboard a client on several. `phoneNumberId` and `allowedPhoneCountries` apply to `whatsapp_waba` only.", "operationId": "createInvitation", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreateRequest" }, "examples": { "basic": { "summary": "Basic invitation", "value": { "clientName": "Acme Corp" } }, "full": { "summary": "Full invitation with all options", "value": { "clientName": "Acme Corp", "clientEmail": "contact@acme.com", "clientPhone": "+14155551234", "expiresInDays": 14, "allowedPhoneCountries": [ "US", "MX" ] } }, "messenger": { "summary": "Messenger invitation (Facebook Page)", "value": { "clientName": "Acme Corp", "clientEmail": "contact@acme.com", "connectionType": "messenger" } } } } } }, "responses": { "201": { "description": "Invitation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List invitations", "description": "List partner invitations for this project.", "operationId": "listInvitations", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/InvitationStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of invitations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/invitations/{invitationId}": { "get": { "summary": "Get invitation", "operationId": "getInvitation", "parameters": [ { "$ref": "#/components/parameters/InvitationIdParam" } ], "responses": { "200": { "description": "Invitation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invitation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/invitations/{invitationId}/cancel": { "post": { "summary": "Cancel invitation", "description": "Cancel an active invitation. The client will no longer be able to use the invitation link.", "operationId": "cancelInvitation", "parameters": [ { "$ref": "#/components/parameters/InvitationIdParam" } ], "responses": { "200": { "description": "Invitation cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } } }, "400": { "description": "Cannot cancel this invitation (already completed or cancelled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invitation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/addresses": { "post": { "summary": "Create address", "description": "Create a regulatory address for phone number purchases. Some countries require a verified address before phone numbers can be activated.", "operationId": "createAddress", "tags": [ "Regulatory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressCreateRequest" }, "example": { "firstName": "John", "lastName": "Doe", "streetAddress": "123 Main St", "locality": "Berlin", "postalCode": "10115", "countryCode": "DE" } } } }, "responses": { "201": { "description": "Address created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List addresses", "description": "List regulatory addresses for this project.", "operationId": "listAddresses", "tags": [ "Regulatory" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of addresses.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/addresses/{addressId}": { "get": { "summary": "Get address", "description": "Get a specific regulatory address.", "operationId": "getAddress", "tags": [ "Regulatory" ], "parameters": [ { "$ref": "#/components/parameters/AddressIdParam" } ], "responses": { "200": { "description": "Address details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Address not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete address", "description": "Delete a regulatory address. Cannot delete addresses that are in use.", "operationId": "deleteAddress", "tags": [ "Regulatory" ], "parameters": [ { "$ref": "#/components/parameters/AddressIdParam" } ], "responses": { "204": { "description": "Address deleted." }, "400": { "description": "Cannot delete address that is in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Address not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/documents": { "post": { "summary": "Create document", "description": "Create a regulatory document record after uploading the file. Use the upload-url endpoint first to get an upload URL.", "operationId": "createRegulatoryDocument", "tags": [ "Regulatory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryDocumentCreateRequest" }, "example": { "name": "Passport Scan", "documentType": "passport", "storageId": "kg2abc123...", "mimeType": "image/jpeg", "fileSize": 102400 } } } }, "responses": { "201": { "description": "Document created and uploaded to verification provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryDocumentResponse" } } } }, "400": { "description": "Invalid request or upload failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List documents", "description": "List regulatory documents for this project.", "operationId": "listRegulatoryDocuments", "tags": [ "Regulatory" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of documents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RegulatoryDocument" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/documents/upload-url": { "post": { "summary": "Get document upload URL", "description": "Get a presigned URL to upload a document file. After uploading, use the storageId to create the document record.", "operationId": "getRegulatoryDocumentUploadUrl", "tags": [ "Regulatory" ], "responses": { "200": { "description": "Upload URL generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/documents/{documentId}": { "get": { "summary": "Get document", "description": "Get a specific regulatory document.", "operationId": "getRegulatoryDocument", "tags": [ "Regulatory" ], "parameters": [ { "$ref": "#/components/parameters/RegulatoryDocumentIdParam" } ], "responses": { "200": { "description": "Document details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryDocumentResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete document", "description": "Delete a regulatory document. Cannot delete verified documents.", "operationId": "deleteRegulatoryDocument", "tags": [ "Regulatory" ], "parameters": [ { "$ref": "#/components/parameters/RegulatoryDocumentIdParam" } ], "responses": { "204": { "description": "Document deleted." }, "400": { "description": "Cannot delete a verified document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent": { "get": { "summary": "Get agent", "description": "Get the AI agent configuration for a sender.", "operationId": "getAgent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "Agent configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender or agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create agent", "description": "Create an AI agent for a sender. Each sender can have at most one agent.", "operationId": "createAgent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateRequest" }, "example": { "name": "Customer Support", "provider": "openai", "model": "gpt-4o-mini", "systemPrompt": "You are a helpful customer support agent. Be friendly and concise.", "apiKey": "sk-..." } } } }, "responses": { "201": { "description": "Agent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request or agent already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update agent", "description": "Update an AI agent's configuration.", "operationId": "updateAgent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdateRequest" } } } }, "responses": { "200": { "description": "Agent updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender or agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete agent", "description": "Delete an AI agent.", "operationId": "deleteAgent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "204": { "description": "Agent deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender or agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/stats": { "get": { "summary": "Get agent statistics", "description": "Get statistics for an AI agent including invocations, tokens, and costs.\n\nCovers the messaging channels only. Voice calls are not counted here: a call is a multi-turn conversation rather than one inbound message and one reply, so it is recorded as a call, not an execution. An agent that only answers phone calls reports zeros on every field. Use `GET /v1/calls` for voice activity, duration, and cost.", "operationId": "getAgentStats", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "responses": { "200": { "description": "Agent statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStats" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/executions": { "get": { "summary": "List agent executions", "description": "List recent agent executions with pagination.\n\nAn execution is one inbound message answered by the agent, so this covers the messaging channels only. Voice calls are never listed here regardless of how many the agent handled. Use `GET /v1/calls` (and `GET /v1/calls/{callId}` for the transcript) for voice.", "operationId": "listAgentExecutions", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/AgentExecutionStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of executions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentExecution" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/executions/{executionId}": { "get": { "summary": "Get a single agent execution", "description": "Fetch full details for one execution — including `errorMessage`, `errorCode`, and `responseText`. Use this to debug failures surfaced by the list endpoint.", "operationId": "getAgentExecution", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "execution" ], "properties": { "execution": { "$ref": "#/components/schemas/AgentExecution" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent or execution not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/flows": { "get": { "summary": "List flows", "description": "List flows for an agent.", "operationId": "listAgentFlows", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "name": "enabled", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of flows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFlow" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create flow", "description": "Create a new flow for an agent.", "operationId": "createAgentFlow", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowCreateRequest" }, "example": { "name": "Lead Capture", "description": "Capture lead information", "trigger": { "type": "keyword", "keywords": [ "info", "pricing", "demo" ] }, "steps": [ { "id": "welcome", "type": "message", "config": { "text": "Thanks for your interest! Let me get some info." }, "nextStepId": "ask_name" }, { "id": "ask_name", "type": "collect", "config": { "variable": "name", "prompt": "What's your name?" } } ] } } } }, "responses": { "201": { "description": "Flow created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/flows/{flowId}": { "get": { "summary": "Get flow", "description": "Get a specific flow.", "operationId": "getAgentFlow", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/FlowIdParam" } ], "responses": { "200": { "description": "Flow details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Flow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update flow", "description": "Update a flow.", "operationId": "updateAgentFlow", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/FlowIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowUpdateRequest" } } } }, "responses": { "200": { "description": "Flow updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Flow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete flow", "description": "Delete a flow. Cannot delete flows with active sessions.", "operationId": "deleteAgentFlow", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/FlowIdParam" } ], "responses": { "204": { "description": "Flow deleted." }, "400": { "description": "Cannot delete flow with active sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Flow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/flows/{flowId}/duplicate": { "post": { "summary": "Duplicate flow", "description": "Create a copy of an existing flow with a new name.", "operationId": "duplicateAgentFlow", "tags": [ "Agent Flows" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/FlowIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowDuplicateRequest" }, "example": { "newName": "Lead Capture (Copy)" } } } }, "responses": { "201": { "description": "Flow duplicated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Flow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/tools": { "get": { "summary": "List tools", "description": "List tools for an agent.", "operationId": "listAgentTools", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "name": "enabled", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tools.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create tool", "description": "Create a new tool for an agent. Tools allow the agent to call external webhooks.", "operationId": "createAgentTool", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCreateRequest" }, "example": { "name": "get_order_status", "description": "Get the status of a customer order", "webhookUrl": "https://api.example.com/webhooks/order-status", "webhookSecret": "whsec_...", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order ID to look up" } }, "required": [ "order_id" ] } } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/tools/{toolId}": { "get": { "summary": "Get tool", "description": "Get a specific tool.", "operationId": "getAgentTool", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/ToolIdParam" } ], "responses": { "200": { "description": "Tool details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update tool", "description": "Update a tool.", "operationId": "updateAgentTool", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/ToolIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUpdateRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete tool", "description": "Delete a tool.", "operationId": "deleteAgentTool", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/ToolIdParam" } ], "responses": { "204": { "description": "Tool deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/tools/{toolId}/test": { "post": { "summary": "Test tool", "description": "Run a tool with the parameters you supply and return what it answered.\n\nThe call is synchronous: the response carries the tool's status, body, and duration, so a green result is evidence the tool ran rather than evidence it was accepted. Each run is also recorded and readable afterwards via `GET /v1/senders/{senderId}/agent/tools/{toolId}/test-runs`.\n\nA tool that answers with an error is reported as a run with `success: false` — the endpoint itself still returns 200. This fires the tool's real webhook, so a test has whatever side effects the tool has.", "operationId": "testAgentTool", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/ToolIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolTestRequest" }, "example": { "testParams": { "order_id": "ORD-12345" } } } } }, "responses": { "200": { "description": "The tool ran. Check `run.success` for what it answered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolTestResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/tools/{toolId}/test-runs": { "get": { "summary": "List tool test runs", "description": "Recent runs of this tool triggered from the test endpoint, newest first. Covers manual tests only: a tool called by an agent during a real conversation is not recorded here.", "operationId": "listAgentToolTestRuns", "tags": [ "Agent Tools" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/ToolIdParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Recent test runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentToolTestRun" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/knowledge-bases": { "get": { "summary": "List knowledge bases", "description": "List knowledge bases for an agent.", "operationId": "listAgentKnowledgeBases", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of knowledge bases.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentKnowledgeBase" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create knowledge base", "description": "Create a new knowledge base for an agent.", "operationId": "createAgentKnowledgeBase", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseCreateRequest" }, "example": { "name": "Product FAQ", "description": "Frequently asked questions about our products" } } } }, "responses": { "201": { "description": "Knowledge base created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/knowledge-bases/{kbId}": { "get": { "summary": "Get knowledge base", "description": "Get a specific knowledge base.", "operationId": "getAgentKnowledgeBase", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" } ], "responses": { "200": { "description": "Knowledge base details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update knowledge base", "description": "Update a knowledge base.", "operationId": "updateAgentKnowledgeBase", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseUpdateRequest" } } } }, "responses": { "200": { "description": "Knowledge base updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete knowledge base", "description": "Delete a knowledge base and all its documents.", "operationId": "deleteAgentKnowledgeBase", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" } ], "responses": { "204": { "description": "Knowledge base deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/knowledge-bases/{kbId}/documents": { "get": { "summary": "List documents", "description": "List documents in a knowledge base.", "operationId": "listAgentDocuments", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of documents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDocument" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create document", "description": "Add a document to a knowledge base. The document will be automatically processed for RAG.", "operationId": "createAgentDocument", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreateRequest" }, "example": { "title": "Return Policy", "content": "Our return policy allows returns within 30 days of purchase..." } } } }, "responses": { "201": { "description": "Document created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/senders/{senderId}/agent/knowledge-bases/{kbId}/documents/{docId}": { "get": { "summary": "Get document", "description": "Get a single document from a knowledge base.", "operationId": "getAgentDocument", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" }, { "$ref": "#/components/parameters/DocumentIdParam" } ], "responses": { "200": { "description": "Document details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update document", "description": "Update a document's title or content. Updating content reprocesses the document for RAG.", "operationId": "updateAgentDocument", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" }, { "$ref": "#/components/parameters/DocumentIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdateRequest" } } } }, "responses": { "200": { "description": "Document updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete document", "description": "Delete a document from a knowledge base.", "operationId": "deleteAgentDocument", "tags": [ "Agent Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/SenderIdParam" }, { "$ref": "#/components/parameters/KnowledgeBaseIdParam" }, { "$ref": "#/components/parameters/DocumentIdParam" } ], "responses": { "204": { "description": "Document deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/urls": { "post": { "summary": "Submit URL for verification", "description": "Submit a URL for verification. URLs are automatically checked against Google Web Risk API. Safe URLs are auto-approved, malicious URLs are blocked. URL shorteners (bit.ly, t.co, etc.) are always blocked.\n\n**Important:** All SMS and Email messages containing URLs require those URLs to be verified before the message can be sent. This endpoint allows pre-verification of URLs.", "operationId": "submitUrl", "tags": [ "URL Verification" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedUrlSubmitRequest" }, "example": { "url": "https://example.com/page" } } } }, "responses": { "200": { "description": "URL already verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedUrlResponse" } } } }, "201": { "description": "URL verified and approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedUrlResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "URL blocked (malicious, rejected, or shortener).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "malicious": { "summary": "Malicious URL", "value": { "code": "url_malicious", "message": "URL has been flagged as potentially harmful by security systems. This incident has been logged.", "details": { "urls": [ "https://malicious-site.com" ], "threatTypes": [ "MALWARE", "SOCIAL_ENGINEERING" ], "warning": "fraud_prevention" } } }, "shortener": { "summary": "URL shortener blocked", "value": { "code": "url_shortener_blocked", "message": "URL shorteners are not allowed. Please use the full destination URL.", "details": { "urls": [ "https://bit.ly/abc123" ], "reason": "url_shorteners_hidden_destination" } } }, "rejected": { "summary": "URL rejected", "value": { "code": "url_rejected", "message": "URL has been rejected by our security team.", "details": { "urls": [ "https://rejected-site.com" ], "warning": "fraud_prevention" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List verified URLs", "description": "List URLs that have been verified for this project.", "operationId": "listUrls", "tags": [ "URL Verification" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/VerifiedUrlStatus" }, "description": "Filter by verification status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of verified URLs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VerifiedUrl" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/urls/{urlId}": { "get": { "summary": "Get URL details", "description": "Get details of a specific verified URL.", "operationId": "getUrl", "tags": [ "URL Verification" ], "parameters": [ { "$ref": "#/components/parameters/UrlIdParam" } ], "responses": { "200": { "description": "URL details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedUrlResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "URL not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/me": { "get": { "summary": "Get current API key context", "description": "Returns the project, team, and API key metadata bound to the current Bearer token. Used by CLIs and SDKs to confirm which project they will operate on.", "operationId": "getMe", "tags": [ "Account" ], "responses": { "200": { "description": "Context for the API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project", "team", "apiKey", "isTestMode" ], "properties": { "project": { "type": "object", "required": [ "id", "name", "isSubAccount" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "isSubAccount": { "type": "boolean" } } }, "team": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } } }, "apiKey": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "isTestMode": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/balance": { "get": { "summary": "Get balance", "description": "Get balance for the API key's team. If the API key belongs to a sub-account, also includes the sub-account's total spending and credit limit.", "operationId": "getBalance", "tags": [ "Balance" ], "responses": { "200": { "description": "Balance details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" }, "example": { "balance": 150000, "currency": "usd", "creditLimit": 100000, "totalSpent": 35000, "isSubAccount": true } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sub-accounts": { "post": { "summary": "Create sub-account", "description": "Create a new sub-account (project) with its own API key. All charges are billed to the parent team's balance. Use creditLimit to set a spending cap. The sub-account's API key is returned only in the creation response. Requires a parent project API key; sub-account API keys receive HTTP 403.", "operationId": "createSubAccount", "tags": [ "Sub-Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountCreateRequest" }, "examples": { "basic": { "summary": "Basic sub-account", "value": { "name": "Client ABC" } }, "with_limit": { "summary": "Sub-account with spending cap", "value": { "name": "Client ABC", "externalId": "client_123", "creditLimit": 100000 } } } } } }, "responses": { "201": { "description": "Sub-account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List sub-accounts", "description": "List sub-accounts for this team. Requires a parent project API key; sub-account API keys receive HTTP 403.", "operationId": "listSubAccounts", "tags": [ "Sub-Accounts" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of sub-accounts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubAccount" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sub-accounts/{id}": { "get": { "summary": "Get sub-account", "operationId": "getSubAccount", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "responses": { "200": { "description": "Sub-account details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Get sub-account. Requires a parent project API key; sub-account API keys receive HTTP 403." }, "patch": { "summary": "Update sub-account", "operationId": "updateSubAccount", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountUpdateRequest" } } } }, "responses": { "200": { "description": "Sub-account updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Update sub-account. Requires a parent project API key; sub-account API keys receive HTTP 403." }, "delete": { "summary": "Deactivate sub-account", "description": "Deactivate a sub-account. Remaining balance is returned to the parent team and all API keys are revoked. Requires a parent project API key; sub-account API keys receive HTTP 403.", "operationId": "deactivateSubAccount", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "responses": { "200": { "description": "Sub-account deactivated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "keysRevoked" ], "properties": { "message": { "type": "string", "example": "Sub-account deactivated" }, "keysRevoked": { "type": "integer", "description": "Number of API keys revoked." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sub-accounts/{id}/balance": { "get": { "summary": "Get sub-account spending", "description": "Get spending information for a sub-account. Returns the parent team's balance, the sub-account's total spending, and its credit limit (spending cap). Requires a parent project API key; sub-account API keys receive HTTP 403.", "operationId": "getSubAccountBalance", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "responses": { "200": { "description": "Sub-account balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sub-accounts/{id}/api-keys": { "get": { "summary": "List sub-account API keys", "operationId": "listSubAccountApiKeys", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "responses": { "200": { "description": "List of API keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubAccountApiKey" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "description": "List sub-account API keys. Requires a parent project API key; sub-account API keys receive HTTP 403." }, "post": { "summary": "Create sub-account API key", "operationId": "createSubAccountApiKey", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubAccountApiKeyCreateRequest" }, "example": { "name": "Production Key", "environment": "live" } } } }, "responses": { "201": { "description": "API key created. The full key is only returned once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "object", "required": [ "id", "key", "name", "environment" ], "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "live", "test" ] } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Create sub-account API key. Requires a parent project API key; sub-account API keys receive HTTP 403." } }, "/v1/sub-accounts/{id}/api-keys/{keyId}": { "delete": { "summary": "Revoke sub-account API key", "operationId": "revokeSubAccountApiKey", "tags": [ "Sub-Accounts" ], "parameters": [ { "$ref": "#/components/parameters/SubAccountIdParam" }, { "$ref": "#/components/parameters/SubAccountApiKeyIdParam" } ], "responses": { "204": { "description": "API key revoked." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Sub-account API keys cannot manage sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sub-account or API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Revoke sub-account API key. Requires a parent project API key; sub-account API keys receive HTTP 403." } }, "/v1/10dlc/brands": { "get": { "summary": "List 10DLC brands", "description": "List 10DLC brand registrations for this project.", "operationId": "listTenDlcBrands", "tags": [ "10DLC" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of brands.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenDlcBrand" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create 10DLC brand", "description": "Create a 10DLC brand registration. The brand starts in draft status. Submit it for review using the submit endpoint.", "operationId": "createTenDlcBrand", "tags": [ "10DLC" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandCreateRequest" }, "example": { "entityType": "PRIVATE_PROFIT", "displayName": "Acme Corp", "companyName": "Acme Corporation", "ein": "12-3456789", "email": "compliance@acme.com", "phone": "+14155551234", "street": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94102", "country": "US", "website": "https://acme.com", "vertical": "Technology" } } } }, "responses": { "201": { "description": "Brand created in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/brands/use-cases": { "get": { "summary": "List 10DLC use cases", "description": "List available use cases for 10DLC campaign registration.", "operationId": "listTenDlcUseCases", "tags": [ "10DLC" ], "responses": { "200": { "description": "List of available use cases.", "content": { "application/json": { "schema": { "type": "object", "required": [ "useCases" ], "properties": { "useCases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/brands/{brandId}": { "get": { "summary": "Get 10DLC brand", "operationId": "getTenDlcBrand", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcBrandIdParam" } ], "responses": { "200": { "description": "Brand details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update 10DLC brand", "description": "Update a 10DLC brand in draft status. Cannot update after submission.", "operationId": "updateTenDlcBrand", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcBrandIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandUpdateRequest" } } } }, "responses": { "200": { "description": "Brand updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandResponse" } } } }, "400": { "description": "Invalid request or brand already submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete 10DLC brand", "operationId": "deleteTenDlcBrand", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcBrandIdParam" } ], "responses": { "204": { "description": "Brand deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/brands/{brandId}/submit": { "post": { "summary": "Submit 10DLC brand for review", "description": "Submit a draft brand to The Campaign Registry (TCR) for vetting. The brand must be in draft status. TCR's one-time $4 brand registration fee is charged from your balance at submission (passed through at cost) and refunded if the carrier rejects the registration. A team that already paid this fee through the compliance flow is not charged again. Campaign registration is billed separately when a campaign is submitted.", "operationId": "submitTenDlcBrand", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcBrandIdParam" } ], "responses": { "200": { "description": "Brand submitted for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandResponse" } } } }, "400": { "description": "Brand already submitted or invalid status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/brands/{brandId}/sync": { "post": { "summary": "Sync 10DLC brand status", "description": "Sync the brand status with the registration provider. Use this to check for approval updates after submission.", "operationId": "syncTenDlcBrand", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcBrandIdParam" } ], "responses": { "200": { "description": "Brand status synced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcBrandResponse" } } } }, "400": { "description": "Brand has not been submitted yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns": { "get": { "summary": "List 10DLC campaigns", "description": "List 10DLC campaign registrations for this project.", "operationId": "listTenDlcCampaigns", "tags": [ "10DLC" ], "parameters": [ { "name": "brandId", "in": "query", "description": "Filter campaigns by brand ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of campaigns.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenDlcCampaign" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create 10DLC campaign", "description": "Create a 10DLC campaign under an existing brand. The campaign starts in draft status. Submit it for carrier review using the submit endpoint.", "operationId": "createTenDlcCampaign", "tags": [ "10DLC" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignCreateRequest" }, "example": { "brandId": "brand_abc123", "name": "Order Notifications", "useCase": "ACCOUNT_NOTIFICATION", "description": "Send order status updates and shipping notifications to customers who opted in.", "sampleMessages": [ "Hi {{name}}, your order #{{order_id}} has shipped! Track it at {{url}}", "Your order #{{order_id}} has been delivered. Thank you for your purchase!" ], "subscriberOptIn": true, "subscriberOptOut": true, "subscriberHelp": true, "numberPooling": false, "directLending": false, "embeddedLink": true, "embeddedPhone": false, "affiliateMarketing": false, "ageGated": false } } } }, "responses": { "201": { "description": "Campaign created in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns/{campaignId}": { "get": { "summary": "Get 10DLC campaign", "operationId": "getTenDlcCampaign", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "responses": { "200": { "description": "Campaign details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update 10DLC campaign", "description": "Update a 10DLC campaign in draft status. Cannot update after submission.", "operationId": "updateTenDlcCampaign", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Campaign updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignResponse" } } } }, "400": { "description": "Invalid request or campaign already submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete 10DLC campaign", "operationId": "deleteTenDlcCampaign", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "responses": { "204": { "description": "Campaign deleted." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns/{campaignId}/submit": { "post": { "summary": "Submit 10DLC campaign for review", "description": "Submit a draft campaign for carrier review. The campaign must be in draft status and its brand must be verified. TCR's one-time registration fee is charged from your balance at submission ($15 for standard use cases, $2 for LOW_VOLUME), passed through at cost and refunded if the carrier rejects it. Once approved, the campaign's monthly TCR fee ($10 standard, $2 LOW_VOLUME) is charged from your balance while the campaign is active — see registrationCostCents and monthlyFeeCents on the campaign object.", "operationId": "submitTenDlcCampaign", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "responses": { "200": { "description": "Campaign submitted for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignResponse" } } } }, "400": { "description": "Campaign already submitted or invalid status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns/{campaignId}/sync": { "post": { "summary": "Sync 10DLC campaign status", "description": "Sync the campaign status with the registration provider. Use this to check for approval updates after submission.", "operationId": "syncTenDlcCampaign", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "responses": { "200": { "description": "Campaign status synced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcCampaignResponse" } } } }, "400": { "description": "Campaign has not been submitted yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns/{campaignId}/phone-numbers": { "get": { "summary": "List campaign phone number assignments", "description": "List phone numbers assigned to a 10DLC campaign.", "operationId": "listTenDlcCampaignPhoneNumbers", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "responses": { "200": { "description": "List of phone number assignments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenDlcPhoneNumberAssignment" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Assign phone number to campaign", "description": "Assign a US phone number to an approved 10DLC campaign. The campaign must be in approved status.", "operationId": "assignTenDlcPhoneNumber", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcPhoneNumberAssignRequest" }, "example": { "phoneNumberId": "pn_abc123" } } } }, "responses": { "201": { "description": "Phone number assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenDlcAssignmentResponse" } } } }, "400": { "description": "Campaign not approved or invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign or phone number not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/10dlc/campaigns/{campaignId}/phone-numbers/{assignmentId}": { "delete": { "summary": "Unassign phone number from campaign", "description": "Remove a phone number assignment from a 10DLC campaign.", "operationId": "unassignTenDlcPhoneNumber", "tags": [ "10DLC" ], "parameters": [ { "$ref": "#/components/parameters/TenDlcCampaignIdParam" }, { "$ref": "#/components/parameters/TenDlcAssignmentIdParam" } ], "responses": { "204": { "description": "Phone number unassigned." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign or assignment not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions": { "post": { "summary": "Create function", "description": "Create a new Zavu Function. The function starts in `draft` status. A dedicated API key is auto-provisioned and injected as the `ZAVU_API_KEY` secret so the function can call back into the Zavu API without manual setup.\n\nProvide `sourceCode` to seed the draft. Call `POST /v1/functions/{functionId}/deploy` afterwards to publish.", "operationId": "createFunction", "tags": [ "Functions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionCreateRequest" }, "example": { "slug": "order-bot", "name": "Order Bot", "description": "Replies to order status questions on WhatsApp.", "sourceCode": "import { defineFunction } from '@zavudev/functions';\n\nexport default defineFunction(async (event, ctx) => {\n ctx.log('received', event.type);\n});\n", "dependencies": { "openai": "^4.20.0" } } } } }, "responses": { "201": { "description": "Function created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZavuFunctionResponse" } } } }, "400": { "description": "Invalid request (e.g. duplicate slug, invalid dependencies).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}": { "get": { "summary": "Get function", "operationId": "getFunction", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "200": { "description": "Function details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZavuFunctionResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update function draft", "description": "Update an existing function. `sourceCode` / `dependencies` edit the draft without triggering a build — they go live on the next `POST /v1/functions/{functionId}/deploy`. `httpEnabled` is applied to the deployed function immediately, so turning the public endpoint on or off does not require a redeploy.", "operationId": "updateFunctionDraft", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionUpdateRequest" } } } }, "responses": { "200": { "description": "Draft updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZavuFunctionResponse" } } } }, "400": { "description": "No fields provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete function", "description": "Permanently delete a function and cascade: triggers, secrets, deployment history, managed agents+tools, and revoke the auto-provisioned API key. The AWS Lambda + log group are torn down asynchronously.", "operationId": "deleteFunction", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "200": { "description": "Function deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "400": { "description": "Cannot delete while a deployment is in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/deploy": { "post": { "summary": "Deploy function", "description": "Publish the function. If `sourceCode` or `dependencies` are provided in the body, they replace the current draft before deployment. Returns immediately with a deployment ID — poll `GET /v1/functions/deployments/{deploymentId}` until status is `active` or `failed`.", "operationId": "deployFunction", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionDeployRequest" } } } }, "responses": { "202": { "description": "Deployment queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionDeploymentResponse" } } } }, "400": { "description": "Invalid request or function in a non-deployable state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/deployments/{deploymentId}": { "get": { "summary": "Get deployment", "description": "Fetch a deployment to poll its status during a deploy.", "operationId": "getFunctionDeployment", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionDeploymentIdParam" } ], "responses": { "200": { "description": "Deployment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionDeploymentResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deployment not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/secrets": { "get": { "summary": "List function secrets", "description": "Lists every secret key set on the function. Plaintext is NEVER returned — only the last 4 characters of each value, for visual confirmation.", "operationId": "listFunctionSecrets", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "200": { "description": "Secrets list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "type": "object", "required": [ "id", "key", "valueLast4" ], "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "valueLast4": { "type": "string" }, "syncedToAws": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/secrets/{key}": { "put": { "summary": "Set function secret", "description": "Create or update a secret on a function. Marks the function out-of-sync; the next `POST /deploy` re-publishes the Lambda with the new env. Keys must match `[A-Z_][A-Z0-9_]*` (uppercase env-var style) and cannot start with reserved prefixes (AWS_, LAMBDA_, etc).", "operationId": "setFunctionSecret", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" } } } } } }, "responses": { "200": { "description": "Secret updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Secret created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid key or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Unset function secret", "description": "Remove a secret from a function. Doesn't take effect on the running Lambda until the next deploy.", "operationId": "unsetFunctionSecret", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Secret removed." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Secret not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/git-link": { "post": { "summary": "Link a GitHub repository", "description": "Bind a repository to this function so every push to `branch` deploys it. A function holds at most one link; linking again returns 400.\n\n**The server decides how the link authenticates.** If the project has the Zavu GitHub App installed, the link uses that installation: private repositories work and there is nothing to configure in the repository. Otherwise it falls back to a manual link and the response carries a `webhookSecret` you add to the repository yourself. `connection` says which one you got.\n\nThe repository is not checked against GitHub here, because it cannot be: an owner/repo that does not exist, or that the installation cannot see, is accepted and fails on the first deploy with a fetch error.", "operationId": "createFunctionGitLink", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "example": "acme" }, "repo": { "type": "string", "example": "order-bot" }, "branch": { "type": "string", "default": "main" }, "rootDir": { "type": "string", "description": "Subdirectory holding the project, for monorepos.", "example": "apps/bot" }, "autoDeploy": { "type": "boolean", "default": true } } }, "example": { "owner": "acme", "repo": "order-bot", "branch": "main" } } } }, "responses": { "201": { "description": "Link created. The only response that ever carries `webhookSecret`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRepoLinkResponse" } } } }, "400": { "description": "Invalid owner, repo or branch, or the function is already linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "Get the linked repository", "description": "The link and its last deploy. Never returns the webhook secret.", "operationId": "getFunctionGitLink", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRepoLinkResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No repository is linked to this function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update the linked repository", "description": "Change the branch, the root directory, or whether pushes deploy. Pass at least one field. `rootDir: null` clears the subdirectory.", "operationId": "updateFunctionGitLink", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "type": "string" }, "rootDir": { "type": "string", "nullable": true }, "autoDeploy": { "type": "boolean" } } }, "example": { "autoDeploy": false } } } }, "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRepoLinkResponse" } } } }, "400": { "description": "No fields to update, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No repository is linked to this function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Unlink the repository", "description": "Remove the link. The function and its deployments stay. A manual webhook left in the repository stops being accepted, so remove it there too.", "operationId": "deleteFunctionGitLink", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "204": { "description": "Link removed." }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No repository is linked to this function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/git-link/deploy": { "post": { "summary": "Deploy the linked branch now", "description": "Fetch the linked branch and deploy it without waiting for a push. Returns immediately; follow the outcome with `GET /v1/functions/{functionId}/git-link`, whose `lastStatus` and `lastError` describe the run.", "operationId": "deployFunctionGitLink", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" } ], "responses": { "202": { "description": "Deploy scheduled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled" ], "properties": { "scheduled": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No repository is linked to this function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A deploy for this link is already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/functions/{functionId}/logs": { "get": { "summary": "Tail function logs", "description": "Fetch invocation logs for a function. Logs are paginated via `nextToken`. Pass `startTime` / `endTime` (Unix epoch milliseconds) to bound the window, or `filterPattern` to filter messages.", "operationId": "tailFunctionLogs", "tags": [ "Functions" ], "parameters": [ { "$ref": "#/components/parameters/FunctionIdParam" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start of the log window in Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End of the log window in Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "filterPattern", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Log events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionLogsResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Function not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/calls": { "post": { "summary": "Place a voice call", "description": "Place an outbound voice call answered by the voice agent configured on the sender. Zavu dials the recipient and runs the conversation through its managed voice pipeline (speech recognition, the agent's LLM, and speech synthesis, with real-time interruption handling).\n\n**Requirements:**\n- The Voice Agents feature must be enabled for your team (otherwise `403`).\n- The sender's agent must have `voice.enabled` set to `true`.\n- Not available with test-mode API keys.\n\n**Billing:** Voice calls are billed per minute of connected time plus telephony, deducted from your prepaid balance. A short-duration estimate is reserved when the call is placed; you are charged for the actual duration when the call ends.", "operationId": "createCall", "tags": [ "Voice Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallCreateRequest" }, "examples": { "basic": { "summary": "Outbound call with the default sender", "value": { "to": "+56912345678" } }, "language": { "summary": "Outbound call in a different language", "value": { "to": "+56912345678", "language": "es-ES" } }, "full": { "summary": "Outbound call with overrides", "value": { "to": "+56912345678", "senderId": "sender_12345", "greeting": "Hi, this is Acme calling about your appointment.", "language": "en-US", "maxDurationMinutes": 10, "metadata": { "campaign": "appointment_reminders" } } } } } } }, "responses": { "202": { "description": "Call accepted and dialing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallResponse" } } } }, "400": { "description": "Invalid request, the sender's agent does not have voice enabled, or voice calls are not available in test mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "voice_not_enabled": { "summary": "Agent voice not enabled", "value": { "code": "invalid_request", "message": "The sender's agent does not have voice enabled" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "insufficient_balance", "message": "Insufficient balance to place this call. Please add funds to continue." } } } }, "403": { "description": "Voice Agents is not enabled for this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "forbidden", "message": "Voice Agents is not enabled for this team" } } } }, "404": { "description": "Sender or agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "summary": "List voice calls", "description": "List voice calls for this project, most recent first. Transcripts are omitted from the list; fetch a single call to get its transcript.", "operationId": "listCalls", "tags": [ "Voice Agents" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/VoiceCallStatus" } }, { "name": "direction", "in": "query", "schema": { "$ref": "#/components/schemas/VoiceCallDirection" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of voice calls.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceCall" } }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Voice Agents is not enabled for this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/calls/{callId}": { "get": { "summary": "Get voice call", "description": "Retrieve a single voice call, including its full transcript once the conversation has produced turns.", "operationId": "getCall", "tags": [ "Voice Agents" ], "parameters": [ { "$ref": "#/components/parameters/CallIdParam" } ], "responses": { "200": { "description": "Voice call details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Voice Agents is not enabled for this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/calls/{callId}/hangup": { "post": { "summary": "Hang up a voice call", "description": "End an active voice call. The call must still be ringing or in progress. Not available with test-mode API keys.", "operationId": "hangupCall", "tags": [ "Voice Agents" ], "parameters": [ { "$ref": "#/components/parameters/CallIdParam" } ], "responses": { "202": { "description": "Hang up accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallResponse" } } } }, "400": { "description": "The call is not active and cannot be hung up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Voice Agents is not enabled for this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/agent-templates": { "get": { "summary": "List factory agents", "description": "List the factory agents available to scaffold with `npx zavudev agents pull`. Each entry is a ready-made voice or text agent (system prompt, skills, and — for voice agents — a co-located voice config).", "operationId": "listAgentTemplates", "tags": [ "Agents" ], "responses": { "200": { "description": "List of factory agents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTemplateSummary" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/agent-templates/{templateId}": { "get": { "summary": "Get a factory agent", "description": "Fetch a single factory agent fully rendered: the function files to scaffold (an `index.ts` that declares the agent with `defineAgent` and its skills with `defineTool`) plus the secrets it needs. This is what `npx zavudev agents pull