> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeptar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start agent conversation



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/{agentId}/conversations
openapi: 3.0.0
info:
  title: Zeptar API
  description: >-
    The Zeptar API is organized around REST. All requests and responses are
    JSON. Endpoints are scoped to the authenticated user’s active organization
    unless the path specifies an organization explicitly.
  version: v1
  contact: {}
servers:
  - url: https://api.zeptar.com
    description: Production
  - url: http://localhost:3001
    description: Local development
security: []
tags:
  - name: dashboard
    description: Workspace analytics dashboard
  - name: api-keys
    description: Create, list, update, and revoke API keys
  - name: request-log
    description: Browse, filter, and export the history of authenticated API requests
  - name: voices
    description: Voices available for speech synthesis
  - name: llm
    description: Large language models available for agents
  - name: convai/agents
    description: CRUD on conversational AI agents
  - name: convai/conversations
    description: Start a preview conversation against an agent
  - name: conversations
    description: Browse conversation history, transcripts, tags, and analysis
  - name: organizations
    description: List and look up workspaces (organizations)
  - name: organizations/members
    description: Add and remove members from an org
  - name: me
    description: The current authenticated user
  - name: me/workspace-invitations
    description: Pending workspace invites for the current user
paths:
  /v1/agents/{agentId}/conversations:
    post:
      tags:
        - conversations
      summary: Start agent conversation
      operationId: ConversationsController_start
      parameters:
        - name: agentId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConversationDto'
      responses:
        '201':
          description: ''
      security:
        - apiKey: []
        - cookie: []
components:
  schemas:
    StartConversationDto:
      type: object
      properties:
        overrides:
          description: >-
            Per-conversation overrides for the agent configuration. Useful for
            previewing unsaved draft changes without persisting them. Every
            field is optional and additive — an absent field falls back to the
            pinned version.
          allOf:
            - $ref: '#/components/schemas/OverridesDto'
        branch_id:
          type: string
          description: Pin the conversation to a specific branch (uses its head_version).
        version_id:
          type: string
          description: Pin the conversation to a specific version.
        modality:
          type: string
          description: >-
            Conversation modality. 'text' persists the row as text and signs a
            token that cannot publish a microphone (typed chat only). Defaults
            to 'voice'.
          enum:
            - voice
            - text
    OverridesDto:
      type: object
      properties:
        system_prompt:
          type: string
          description: >-
            Replaces the agent`s persisted system prompt for this conversation
            only. Used by the web UI to preview unsaved drafts. Trimmed;
            non-empty; up to 20,000 chars.
          example: You are a helpful onboarding assistant.
          maxLength: 20000
        first_message:
          type: object
          description: >-
            Overrides the first message the agent speaks for this conversation
            only. null/empty → the agent waits for the user. Up to 20,000 chars.
          example: Hello! How can I help you today?
          nullable: true
          maxLength: 20000
        first_message_wait_time_seconds:
          type: object
          description: >-
            Overrides the wait time (seconds the agent waits for the user to
            speak first when first_message is empty; -1 → wait indefinitely,
            null → default 7s) for this conversation only.
          example: 7
          nullable: true
        language:
          description: Overrides the language config for this conversation only.
          allOf:
            - $ref: '#/components/schemas/OverrideLanguageDto'
        llm:
          description: Overrides the LLM config for this conversation only.
          allOf:
            - $ref: '#/components/schemas/OverrideLlmDto'
        tts:
          description: Overrides the TTS (voice) config for this conversation only.
          allOf:
            - $ref: '#/components/schemas/OverrideTtsDto'
        interruptible:
          type: boolean
          description: >-
            Overrides whether the user can interrupt the agent for this
            conversation only.
          example: true
        language_voice_overrides:
          type: object
          description: >-
            Overrides the per-language voice map for this conversation only
            (language code → voice config).
          additionalProperties: true
        prompt_timezone:
          type: object
          description: >-
            Overrides the prompt timezone (IANA, e.g. Europe/Paris; null → off)
            for this conversation only.
          example: Europe/Paris
          nullable: true
    OverrideLanguageDto:
      type: object
      properties:
        default:
          type: string
          example: en
        additional:
          example:
            - de
          type: array
          items:
            type: string
    OverrideLlmDto:
      type: object
      properties:
        provider:
          type: string
          example: openai
        model:
          type: string
          example: gpt-5.2-chat-latest
        temperature:
          type: object
          example: 0.7
          nullable: true
    OverrideTtsDto:
      type: object
      properties:
        provider:
          type: string
          example: cartesia
        voice_id:
          type: string
          example: 9626c31c-bec5-4cca-baa8-f8ba9e84c8bc
        model:
          type: string
          example: sonic-3
        settings:
          type: object
          additionalProperties:
            type: number
        voice_name:
          type: string
          example: Jacqueline
  securitySchemes:
    apiKey:
      scheme: bearer
      bearerFormat: zsk_…
      type: http
      description: >-
        API key issued via `POST /v1/api-keys`. Prefix is `zsk_`. Pass as
        `Authorization: Bearer zsk_…`. Scopes are enforced per key.
    cookie:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: >-
        Session cookie set by `auth.api.signInEmail` (or the OAuth flow).
        Forwarded automatically by the browser; copy via `document.cookie` for
        server-to-server calls during development.

````