KaiCalls Agents API

openapi: 3.2.0
info:
  title: KaiCalls Public Agents API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Agents
paths:
  /v1/agents:
    get:
      summary: List or retrieve workspace agents.
      x-required-scopes: agents:read
      tags:
      - Agents
      operationId: getV1Agents
      x-operation-id-source: derived
    post:
      summary: Create an agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentCreate'
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: postV1Agents
      x-operation-id-source: derived
    patch:
      summary: Update an agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentUpdate'
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: patchV1Agents
      x-operation-id-source: derived
  /v1/agents/enable-multilingual:
    post:
      summary: Safely enable automatic handling for 2-4 selected caller languages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - languages
              properties:
                agent_id:
                  type: string
                  format: uuid
                languages:
                  type: array
                  minItems: 2
                  maxItems: 4
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                    - en
                    - es
                    - fr
                    - de
                    - hi
                    - ru
                    - pt
                    - ja
                    - it
                    - nl
      responses:
        '200':
          description: Language update committed after all required evaluations pass.
        '409':
          description: Preflight rejected because of invalid state or configuration drift.
        '422':
          description: Evaluation gate failed; the original configuration was restored and verified.
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: postV1AgentsEnableMultilingual
      x-operation-id-source: derived
  /v1/agents/versions:
    get:
      summary: List hashed, redacted assistant config versions for an agent (rollback lineage).
      parameters:
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
      - name: version
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Agent config version list or object
      x-required-scopes: agents:read
      tags:
      - Agents
      operationId: getV1AgentsVersions
      x-operation-id-source: derived
  /v1/agents/tools:
    get:
      summary: List which agent tools (e.g.
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Enabled + available tool lists
      x-required-scopes: agents:read
      tags:
      - Agents
      operationId: getV1AgentsTools
      x-operation-id-source: derived
    patch:
      summary: Enable and/or disable agent tools on an agent's assistant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Agent id
                enable:
                  type: array
                  items:
                    type: string
                disable:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated enabled/disabled tool results
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: patchV1AgentsTools
      x-operation-id-source: derived
  /v1/agents/rollback:
    post:
      summary: Restore an agent to a previously-deployed config version (greeting / voice /…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              properties:
                agent_id:
                  type: string
                version_number:
                  type: integer
                  description: Target version number (one of version_number / version_id required).
                version_id:
                  type: string
                  description: Target version id (one of version_number / version_id required).
                reason:
                  type: string
      responses:
        '200':
          description: Rollback applied; returns the new active config version.
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: postV1AgentsRollback
      x-operation-id-source: derived
  /v1/agents/persona:
    post:
      summary: Load a structured mystery-shop persona into an agent (Intake Audit).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentPersonaLoad'
      responses:
        '200':
          description: Persona loaded; returns the agent-update result plus persona_summary.
      x-required-scopes: agents:write
      tags:
      - Agents
      operationId: postV1AgentsPersona
      x-operation-id-source: derived
components:
  schemas:
    agentUpdate:
      title: Update an existing agent
      type: object
      required:
      - id
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        system_prompt:
          type: string
          description: Legacy alias for inbound_prompt.
        inbound_prompt:
          type: string
        outbound_prompt:
          type: string
        sms_prompt:
          type: string
        first_message:
          type: string
        voice_catalog_id:
          type: string
        voice:
          type: object
          additionalProperties: true
        model:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        max_duration:
          type: number
          description: Maximum call duration in seconds.
        advanced_config:
          type: object
          additionalProperties: true
          description: Advanced voice-agent settings, such as endCallPhrases, silenceTimeoutSeconds, stopSpeakingPlan and analysisPlan (the call summary and lead scoring). Webhook servers, credentials, tools and phone numbers cannot be set with an API key.
        transfer_enabled:
          type: boolean
        transfer_phone_number:
          type: string
        owner_change_summary:
          type: string
        owner_change_reason:
          type: string
        override_owner_edits:
          type: boolean
    agentCreate:
      title: Create a business agent
      type: object
      additionalProperties: false
      required:
      - business_id
      - name
      - system_prompt
      properties:
        business_id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
        system_prompt:
          type: string
          minLength: 1
        first_message:
          type: string
        voice_catalog_id:
          type: string
          description: Preferred voice ID from GET /v1/voices.
        voice:
          type: object
          additionalProperties: true
        model:
          type: object
          properties:
            provider:
              type: string
            model:
              type: string
            temperature:
              type: number
        metadata:
          type: object
          additionalProperties: true
    agentPersonaLoad:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: https://www.kaicalls.com/api/v1/schemas/agentPersonaLoad
      title: Agent Persona Load
      type: object
      additionalProperties: false
      required:
      - agent_id
      - persona
      properties:
        agent_id:
          type: string
          format: uuid
        first_message:
          type: string
          description: Optional override of the opener derived from the persona.
        voice:
          type: object
          additionalProperties: true
        model:
          type: object
          additionalProperties: true
        persona:
          type: object
          additionalProperties: false
          required:
          - lead_name
          - scenario
          properties:
            lead_name:
              type: string
              minLength: 1
            scenario:
              type: string
              minLength: 1
            objective:
              type: string
            script:
              type: string
            persona_traits:
              type: string
            facts_to_reveal:
              type: array
              items:
                type: string
            facts_to_withhold:
              type: array
              items:
                type: string
            callback_number:
              type: string
            opener:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.