Echo AI API

openapi: 3.1.0
info:
  title: Echo AI API
  version: '2026-11-06'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-06: 14 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Echo AI has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 14
    pages-with-code: 0
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-06'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://echoai.so/api
  - https://echoai.so/features/api
servers:
- url: https://auth.echoai.so/functions/v1/api
paths:
  /assistant/{assistantid}:
    get:
      operationId: get_assistant_assistantid
      tags:
      - Assistant
      summary: List, create, and update assistants
      x-source: https://echoai.so/api
      parameters:
      - name: assistantid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAssistantAssistantidResponse'
      x-evidence:
        kind: documentation
  /assistants:
    get:
      operationId: get_assistants
      tags:
      - Assistants
      summary: List, create, and update assistants
      x-source: https://echoai.so/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAssistantsResponse'
      x-evidence:
        kind: documentation
  /chat:
    post:
      operationId: post_chat
      tags:
      - Chat
      summary: POST a message and stream the reply via SSE
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostChatRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostChatResponse'
      x-evidence:
        kind: documentation
  /chat/stream:
    post:
      operationId: post_chat_stream
      tags:
      - Chat
      summary: POST a message and stream the reply via SSE
      x-source: https://echoai.so/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostChatStreamRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostChatStreamResponse'
      x-evidence:
        kind: documentation
  /checkout:
    post:
      operationId: post_checkout
      tags:
      - Checkout
      summary: Generate an API key
      x-source: https://echoai.so/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCheckoutRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCheckoutResponse'
      x-evidence:
        kind: documentation
  /config:
    get:
      operationId: get_config
      tags:
      - Config
      summary: Read conversations, leads, and bookings for any of your Echos
      x-source: https://echoai.so/api
      parameters:
      - name: echo_id
        in: query
        required: false
        schema:
          type: string
      - name: slug
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConfigResponse'
      x-evidence:
        kind: documentation
  /contacts:
    get:
      operationId: get_contacts
      tags:
      - Contacts
      summary: GET /contacts?echo_id= or ?slug=&limit=&since= - returns captured contacts and leads.
      description: Returns captured contacts and leads for the specified Echo.
      x-source: https://echoai.so/api
      parameters:
      - name: echo_id
        in: query
        required: false
        schema:
          type: string
        description: Echo identifier (UUID).
      - name: slug
        in: query
        required: false
        schema:
          type: string
        description: Echo slug.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum number of contacts to return.
      - name: since
        in: query
        required: false
        schema:
          type: string
        description: Return contacts created after this timestamp.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContactsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_contacts
      tags:
      - Contacts
      summary: 'POST /contacts - body: {echo_id|slug, name?, email, phone?, notes?, lead_score?}. Creates or upserts a contact.'
      description: Creates a new contact or updates an existing one for the specified Echo.
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostContactsRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostContactsResponse'
      x-evidence:
        kind: documentation
  /conversations:
    get:
      operationId: get_conversations
      tags:
      - Conversations
      summary: 'GET /conversations?echo_id= or ?slug=&limit=&since= - returns {conversations: [{…}]}, newest first.'
      description: Returns a list of conversations for the specified Echo.
      x-source: https://echoai.so/api
      parameters:
      - name: echo_id
        in: query
        required: false
        schema:
          type: string
        description: Echo identifier (UUID).
      - name: slug
        in: query
        required: false
        schema:
          type: string
        description: Echo slug.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum number of items to return.
      - name: since
        in: query
        required: false
        schema:
          type: string
        description: Return items created after this timestamp.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConversationsResponse'
      x-evidence:
        kind: documentation
  /session/messages:
    post:
      operationId: post_session_messages
      tags:
      - Session
      summary: Read conversations, leads, and bookings for any of your Echos
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSessionMessagesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSessionMessagesResponse'
      x-evidence:
        kind: documentation
  /tickets:
    post:
      operationId: post_tickets
      tags:
      - Tickets
      summary: Creates a support ticket
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostTicketsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /voice/config:
    get:
      operationId: get_voice_config
      tags:
      - Voice
      summary: Voice endpoints
      x-source: https://echoai.so/api
      parameters:
      - name: echo_id
        in: query
        required: false
        schema:
          type: string
      - name: slug
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVoiceConfigResponse'
      x-evidence:
        kind: documentation
  /voice/speak:
    post:
      operationId: post_voice_speak
      tags:
      - Voice
      summary: Voice endpoints
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostVoiceSpeakRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVoiceSpeakResponse'
      x-evidence:
        kind: documentation
  /voice/transcribe:
    post:
      operationId: post_voice_transcribe
      tags:
      - Voice
      summary: Voice endpoints
      x-source: https://echoai.so/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostVoiceTranscribeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVoiceTranscribeResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetAssistantAssistantidResponse:
      type: object
      properties:
        assistant:
          type: object
          description: Echo object plus public settings
    GetAssistantsResponse:
      type: object
      properties:
        assistants:
          type: array
          description: list of {id, name, bio, avatar_url, slug, tone, style, topics}
    PostChatRequest:
      type: object
      properties:
        assistant_id:
          type: string
        message:
          type: string
        session_id:
          type: string
        visitor_id:
          type: string
        session_token:
          type: string
        attachments:
          type: string
        user_email:
          type: string
        timezone:
          type: string
        currency:
          type: string
      required:
      - message
    PostChatResponse:
      type: object
      properties:
        reply:
          type: string
        session_id:
          type: string
        session_token:
          type: string
        assistant:
          type: object
          description: id, name, slug
    PostChatStreamRequest:
      type: object
      properties:
        echo_id|assistant_id|slug:
          type: string
        message:
          type: string
        attachments:
          type: string
        session_id:
          type: string
        session_token:
          type: string
        visitor_id:
          type: string
        user_email:
          type: string
        timezone:
          type: string
        currency:
          type: string
    PostChatStreamResponse:
      type: object
      properties:
        text/event-stream:
          type: string
          description: token deltas
    PostCheckoutRequest:
      type: object
      properties:
        echo_id|slug:
          type: string
        items:
          type: string
        catalogItemId:
          type: string
        quantity:
          type: string
        session_id:
          type: string
        session_token:
          type: string
        successUrl:
          type: string
        cancelUrl:
          type: string
        returnPath:
          type: string
    PostCheckoutResponse:
      type: object
      properties:
        checkout_url:
          type: string
          description: Stripe or Square checkout session URL
    GetConfigResponse:
      type: object
      properties:
        identity:
          type: object
        appearance:
          type: object
        smart_questions:
          type: array
        capabilities:
          type: object
        ticket_categories:
          type: array
    GetContactsResponse:
      type: object
      properties:
        contacts:
          type: array
          description: List of contact objects.
    PostContactsRequest:
      type: object
      properties:
        echo_id:
          type: string
          description: Echo identifier (UUID).
        slug:
          type: string
          description: Echo slug.
        name:
          type: string
          description: Contact name.
        email:
          type: string
          description: Contact email.
        phone:
          type: string
          description: Contact phone number.
        notes:
          type: string
          description: Additional notes about the contact.
        lead_score:
          type: number
          description: Score indicating lead quality.
      required:
      - email
    PostContactsResponse:
      type: object
      properties:
        contact:
          type: object
          description: The created or upserted contact object.
    GetConversationsResponse:
      type: object
      properties:
        conversations:
          type: array
          description: List of conversation objects.
    PostSessionMessagesRequest:
      type: object
      properties:
        session_id:
          type: string
        session_token:
          type: string
      required:
      - session_id
      - session_token
    PostSessionMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          description: list of {role, content, created_at}
    PostTicketsRequest:
      type: object
      properties:
        echo_id|assistant_id|slug:
          type: string
        subject:
          type: string
        message:
          type: string
        email:
          type: string
        category:
          type: string
      required:
      - subject
      - message
      - email
    GetVoiceConfigResponse:
      type: object
      properties:
        voice_settings:
          type: object
    PostVoiceSpeakRequest:
      type: object
      properties:
        echo_id|slug:
          type: string
        text:
          type: string
        voice:
          type: string
      required:
      - text
    PostVoiceSpeakResponse:
      type: object
      properties:
        audio:
          type: string
          description: synthesised audio
    PostVoiceTranscribeRequest:
      type: object
      properties:
        audio:
          type: string
        mime_type:
          type: string
      required:
      - audio
    PostVoiceTranscribeResponse:
      type: object
      properties:
        text:
          type: string
tags:
- name: Assistant
- name: Assistants
- name: Chat
- name: Checkout
- name: Config
- name: Contacts
- name: Conversations
- name: Session
- name: Tickets
- name: Voice