Programmatic access to your Echo

What the API gives you

• POST a message and stream the reply via SSE
• List, create, and update assistants
• Read conversations, leads, and bookings for any of your Echos
• Trigger actions: book a slot, generate an invoice, push a notification

Base URL and auth

All endpoints live under https://auth.echoai.so/functions/v1/api. Authenticate with either "X-API-Key: YOUR_API_KEY" or "Authorization: Bearer YOUR_API_KEY". Requests and responses are JSON (application/json), except POST /chat/stream which returns text/event-stream. Errors return {"error": string} with 400 (validation), 401 (missing or invalid key), 402 (Echo owner out of credits), 403 (key scoped to another Echo), 429 (rate limited) or 500. An Echo is addressed by echo_id (UUID) or slug; assistant-scoped keys resolve it automatically.

Chat endpoints

• POST /chat - body: {assistant_id?: uuid, message: string (required), session_id?: string, visitor_id?: string, session_token?: string, attachments?: array, user_email?: string, timezone?: string, currency?: string}. Returns {reply, session_id, session_token, assistant: {id, name, slug}}.
• POST /chat/stream - body: {echo_id|assistant_id|slug, message: string, attachments?: array, session_id?, session_token?, visitor_id?, user_email?, timezone?, currency?}. Returns a text/event-stream of token deltas, the same stream the Echo page uses. Either message or attachments is required.
• POST /session/messages - body: {session_id: string, session_token: string}. Returns {messages: [{role, content, created_at}]} for one visitor session.

Echo and config endpoints

• GET /assistants - no parameters. Returns {assistants: [{id, name, bio, avatar_url, slug, tone, style, topics}]}. Assistant-scoped keys return a single item.
• GET /assistant/{assistantId} - path parameter assistantId (UUID). Returns the same Echo object plus public settings.
• GET /config or GET /config/{echo_id|slug} - query alternative: ?echo_id= or ?slug=. Returns identity, appearance, smart questions, capabilities and ticket categories for rendering a custom UI.

Commerce, booking and support endpoints

• GET /catalog?echo_id= or ?slug= - returns {items: [...]} with active catalog items only.
• POST /checkout - body: {echo_id|slug, items?: array, catalogItemId?: uuid, quantity?: number, session_id?, session_token?, successUrl?, cancelUrl?, returnPath?}. Returns the Stripe or Square checkout session URL.
• POST /booking/slots - body: {echo_id|slug, date: YYYY-MM-DD, service_id?: uuid, party_size?: number}. Returns available slots for that date.
• POST /booking - body: {echo_id|slug, date, time, name, email, service_id?, party_size?, notes?}. Creates the booking and returns its confirmation payload.
• POST /tickets - body: {echo_id|assistant_id|slug, subject, message, email, category?}. Creates a support ticket.

Voice endpoints

• POST /voice/transcribe - body: {audio: base64 string, mime_type?: string}. Returns {text}.
• POST /voice/speak - body: {echo_id|slug, text: string, voice?: string}. Returns synthesised audio.
• GET /voice/config?echo_id= or ?slug= - returns the voice settings for that Echo.

Data and automation endpoints

• GET /conversations?echo_id= or ?slug=&limit=&since= - returns {conversations: [{id, assistant_id, visitor_id, platform, is_active, metadata, created_at, updated_at, echo_id, echo_slug, echo_name}]}, newest first.
• GET /tickets?echo_id= or ?slug=&limit=&since= - returns new support tickets, used by the Zapier trigger.
• GET /contacts?echo_id= or ?slug=&limit=&since= - returns captured contacts and leads.
• POST /contacts - body: {echo_id|slug, name?, email, phone?, notes?, lead_score?}. Creates or upserts a contact.

Auth

Generate per-Echo API keys in Settings. Keys carry the same row-level permissions as the owning account. Every call is rate limited per key and logged to your API usage history.

OpenAPI

A full OpenAPI 3.1 schema is available for codegen. We also publish a Model Context Protocol server, a ChatGPT custom GPT, a Claude skill, and a Zapier integration for natural-language and no-code access.