dialogbrain-com Calls API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Calls API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Calls
paths:
  /api/v1/calls:
    post:
      tags:
      - Calls
      summary: Create Call
      description: 'Place a call with an agent to a phone number, a Telegram target or a meeting link, and return the call id once dialling has started (202).


        Requires Idempotency-Key: a retried request with the same key returns the original call instead of dialling again.'
      operationId: create_call_api_v1_calls_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '402':
          description: The workspace has not enough credit to place the call.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '409':
          description: The account that would place the call is already in one, or this Idempotency-Key was already used.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
        '422':
          description: The request body failed validation, or the target cannot be reached on its channel (for example a number that is not on WhatsApp).
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
    get:
      tags:
      - Calls
      summary: List Calls
      description: List the workspace's calls, newest first, with status, duration and outcome.
      operationId: list_calls_api_v1_calls_get
      parameters:
      - name: thread_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Only calls on this thread (as delivered in session.completed). A string, not a number: Meet sessions carry non-numeric refs.'
          title: Thread Id
        description: 'Only calls on this thread (as delivered in session.completed). A string, not a number: Meet sessions carry non-numeric refs.'
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO timestamp lower bound on started_at.
          title: Since
        description: ISO timestamp lower bound on started_at.
      - name: until
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO timestamp upper bound on started_at.
          title: Until
        description: ISO timestamp upper bound on started_at.
      - name: with_recording
        in: query
        required: false
        schema:
          type: boolean
          description: Only calls that have a stored recording.
          default: false
          title: With Recording
        description: Only calls that have a stored recording.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/calls/{call_id}:
    get:
      tags:
      - Calls
      summary: Get Call
      description: Return one call with its current status, duration and outcome.
      operationId: get_call_api_v1_calls__call_id__get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/calls/{call_id}/transcript:
    get:
      tags:
      - Calls
      summary: Get Call Transcript
      description: Return the call's transcript as ordered turns with speaker and timestamps, plus the final status. Available during the call and after it.
      operationId: get_call_transcript_api_v1_calls__call_id__transcript_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/calls/{call_id}/hangup:
    post:
      tags:
      - Calls
      summary: Hangup Call
      description: End an active call. Returns success if the call has already ended.
      operationId: hangup_call_api_v1_calls__call_id__hangup_post
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/calls/{call_id}/recording:
    get:
      tags:
      - Calls
      summary: Get Call Recording
      description: Return a time-limited download link for the call recording, or 404 if there is none. With ?redirect=true the response is a 307 to the file.
      operationId: get_call_recording_api_v1_calls__call_id__recording_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: redirect
        in: query
        required: false
        schema:
          type: boolean
          description: Redirect straight to the audio instead of returning JSON — lets `curl -L -o call.ogg` download in one step.
          default: false
          title: Redirect
        description: Redirect straight to the audio instead of returning JSON — lets `curl -L -o call.ogg` download in one step.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '307':
          description: 'With redirect=true: redirect to the time-limited recording URL.'
        '503':
          description: A recording exists but storage could not issue a download URL; retry later.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/voice/tokens:
    post:
      tags:
      - Calls
      summary: Create Voice Token
      description: 'Mint a LiveKit room and token for one of your end users, and return the credentials to hand to your client.


        Requires Idempotency-Key: a retried request returns the room minted the first time instead of starting a second call.'
      operationId: create_voice_token_api_v1_voice_tokens_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceTokenRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceTokenResponse'
        '403':
          description: The widget has voice turned off, or voice is disabled for the workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '404':
          description: No such widget in this workspace, or no voice trigger matches it.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/voice/bridge:
    post:
      tags:
      - Calls
      summary: Create Voice Bridge
      description: 'Bridge an external LiveKit room to an agent.


        Requires Idempotency-Key to prevent duplicate bridges on retry. Returns

        the call_id and initial status (ringing if answer_delay > 0, active if 0).'
      operationId: create_voice_bridge_api_v1_voice_bridge_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceBridgeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceBridgeResponse'
        '400':
          description: Idempotency-Key missing or invalid request.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '403':
          description: Voice is disabled for this workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '404':
          description: Agent not found in this workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '409':
          description: Idempotency-Key already in progress or request conflict.
          content:
            application/json:
              schema:
                type: object
          headers:
            Retry-After:
              schema:
                type: string
        '422':
          description: SSRF validation, token lifetime, or answer_delay validation failed.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '429':
          description: Bridge capacity exhausted.
          content:
            application/json:
              schema:
                type: object
          headers:
            Retry-After:
              schema:
                type: string
components:
  schemas:
    VoiceBridgeResponse:
      properties:
        call_id:
          type: string
          title: Call Id
        room:
          anyOf:
          - type: string
          - type: 'null'
          title: Room
        status:
          type: string
          title: Status
      type: object
      required:
      - call_id
      - room
      - status
      title: VoiceBridgeResponse
      description: Response from bridging a call.
    VoiceTokenRequest:
      properties:
        widget_id:
          type: integer
          title: Widget Id
          description: The widget this call belongs to.
        end_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: End User Id
          description: Your own identifier for the person calling. It identifies them in the room and comes back inside `metadata` on the call events.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Your own correlation data. It is stored with the call and returned on the call events, and is never shown to the agent.
      type: object
      required:
      - widget_id
      title: VoiceTokenRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VoiceBridgeRequest:
      properties:
        livekit_url:
          type: string
          title: Livekit Url
          description: WebSocket URL of your LiveKit server, wss:// only. Private addresses are refused.
        room:
          type: string
          title: Room
          description: Room name in the partner's LiveKit instance.
        token:
          type: string
          title: Token
          description: LiveKit access token for joining the partner's room. Must be valid for at least 300 seconds (or answer_delay_s if longer).
        agent_id:
          type: integer
          title: Agent Id
          description: The DialogBrain agent to handle the call.
        caller_external_identity:
          type: string
          title: Caller External Identity
          description: The caller's participant identity in your room. The bridge listens to this participant only, and its departure ends the call.
        owner_identity:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner Identity
          description: 'The room owner''s participant identity. Only meaningful with a non-zero answer_delay_s: this participant joining means the human answered, and the agent stands down unbilled.'
        end_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: End User Id
          description: Your identifier for the caller. Comes back on the call events inside metadata.
        answer_delay_s:
          anyOf:
          - type: integer
          - type: 'null'
          title: Answer Delay S
          description: 'Seconds to ring the human before the agent answers (0-120). Absent or 0: agent answers immediately.'
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Arbitrary JSON-serializable data. Returned on call events. Max 4 KB.
      type: object
      required:
      - livekit_url
      - room
      - token
      - agent_id
      - caller_external_identity
      title: VoiceBridgeRequest
      description: Request to bridge an external LiveKit room to an agent.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CreateCallRequest:
      properties:
        agent_id:
          type: integer
          title: Agent Id
        target:
          type: string
          minLength: 1
          title: Target
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Greeting
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        channel_account_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Channel Account Id
      type: object
      required:
      - agent_id
      - target
      title: CreateCallRequest
    VoiceTokenResponse:
      properties:
        url:
          type: string
          title: Url
        token:
          type: string
          title: Token
        room:
          type: string
          title: Room
        call_id:
          type: string
          title: Call Id
        expires_at:
          type: string
          title: Expires At
      type: object
      required:
      - url
      - token
      - room
      - call_id
      - expires_at
      title: VoiceTokenResponse