KaiCalls Agent Connections API

openapi: 3.2.0
info:
  title: KaiCalls Public Agent Connections 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: Agent Connections
paths:
  /v1/agent-connections:
    get:
      summary: Discover the connected external agent, all scoped API operations, channel…
      description: Tenant-scoped. Readiness is configuration evidence, not recipient consent, receiver verification or delivery proof. Voice actions delegate to the business voice agent. Enabled assigned inboxes route signed inbound events when subscribed with emails:read; replies use governed, owner-reviewed email campaigns. Realtime external voice and direct autonomous email replies are unavailable.
      parameters:
      - name: business_id
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Connection, delivery configuration, complete operation catalog and channel readiness
        '403':
          description: Business or scope denied
        '503':
          description: Connection storage or readiness unavailable
      x-required-scopes:
        allOf:
        - agents:read
        - sms:read
        - webhooks:read
      tags:
      - Agent Connections
      operationId: getV1AgentConnections
      x-operation-id-source: derived
    post:
      summary: Connect an external agent to a business and its signed event outbox atomically
      description: Requires current owner/admin membership and an assigned Kai agent. New SMS/WhatsApp conversations default to the external agent; explicit conversation handoffs win. This grants no scopes and does not activate carrier service or bypass execution guards. A repeated Idempotency-Key replays the original connection without revealing its signing secret again. Replacements require the current expected_revision.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentConnectionCreate'
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Persisted connection and signing secret on a non-replayed connect only
        '400':
          description: Invalid input
        '403':
          description: Business, scope, membership or agent assignment denied
        '409':
          description: Revision, idempotency or webhook-limit conflict
        '503':
          description: Connection storage not installed
      x-required-scopes:
        allOf:
        - agents:write
        - sms:write
        - webhooks:write
      tags:
      - Agent Connections
      operationId: postV1AgentConnections
      x-operation-id-source: derived
    delete:
      summary: Disconnect an external agent and disable its webhook atomically
      description: Requires current business owner/admin membership. Inherited conversation ownership returns to Kai; explicit handoffs remain. Repeating the same disconnect revision is idempotent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentConnectionDisconnect'
      responses:
        '200':
          description: Disconnected connection receipt
        '403':
          description: Not authorized
        '409':
          description: Stale revision
        '503':
          description: Storage unavailable
      x-required-scopes:
        allOf:
        - agents:write
        - sms:write
        - webhooks:write
      tags:
      - Agent Connections
      operationId: deleteV1AgentConnections
      x-operation-id-source: derived
components:
  schemas:
    agentConnectionDisconnect:
      type: object
      required:
      - expected_revision
      properties:
        business_id:
          type: string
          format: uuid
        expected_revision:
          type: integer
          minimum: 1
    agentConnectionCreate:
      type: object
      required:
      - agent_id
      - external_agent_id
      - webhook_url
      properties:
        business_id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        external_agent_id:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,199}$
        webhook_url:
          type: string
          format: uri
          pattern: ^https://
          maxLength: 2048
        idempotency_key:
          type: string
          pattern: ^[!-~]{1,200}$
          description: Required in the body or Idempotency-Key header.
        expected_revision:
          type: integer
          minimum: 0
          default: 0
        a2a_enabled:
          type: boolean
          default: false
          description: Route public A2A message/send to the signed receiver, which must return a JSON-RPC A2A message. SDK handleA2ARequest/handle_a2a_request connects the receiver to your own agent.
        a2a_url:
          type:
          - string
          - 'null'
          format: uri
          pattern: ^https://
          maxLength: 2048
          description: Optional existing native A2A endpoint; requires a2a_enabled. Omit to use the signed event receiver.
        external_reply_timeout_seconds:
          type:
          - integer
          - 'null'
          minimum: 60
          maximum: 86400
  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.