KaiCalls Communication Runs API

openapi: 3.2.0
info:
  title: KaiCalls Public Communication Runs 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: Communication Runs
paths:
  /v1/communication-runs:
    get:
      summary: List or retrieve communication runs
      x-required-scopes:
        anyOf:
        - communication-runs:read
        - calls:read
        - sms:read
      tags:
      - Communication Runs
      operationId: getV1CommunicationRuns
      x-operation-id-source: derived
    post:
      summary: Create a communication run.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/communicationRunCreate'
      x-required-scopes:
        anyOf:
        - communication-runs:write
        - allOf:
          - calls:write
          - sms:write
      tags:
      - Communication Runs
      operationId: postV1CommunicationRuns
      x-operation-id-source: derived
    patch:
      summary: Pause or cancel a communication run
      x-required-scopes:
        anyOf:
        - communication-runs:write
        - allOf:
          - calls:write
          - sms:write
      tags:
      - Communication Runs
      operationId: patchV1CommunicationRuns
      x-operation-id-source: derived
  /v1/communication-runs/validate:
    post:
      summary: Validate a communication-run payload without scheduling work
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/communicationRunCreate'
      responses:
        '200':
          description: Validation result
      x-required-scopes:
        anyOf:
        - communication-runs:write
        - allOf:
          - calls:write
          - sms:write
      tags:
      - Communication Runs
      operationId: postV1CommunicationRunsValidate
      x-operation-id-source: derived
  /v1/communication-runs/preview:
    post:
      summary: Preview planned run objects, touch counts, and schedule window
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/communicationRunCreate'
      responses:
        '200':
          description: Preview result
      x-required-scopes:
        anyOf:
        - communication-runs:write
        - allOf:
          - calls:write
          - sms:write
      tags:
      - Communication Runs
      operationId: postV1CommunicationRunsPreview
      x-operation-id-source: derived
components:
  schemas:
    communicationRunCreate:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: https://www.kaicalls.com/api/v1/schemas/communicationRunCreate
      title: Communication Run Create
      type: object
      additionalProperties: false
      required:
      - business_id
      - external_ref
      - touches
      properties:
        business_id:
          type: string
          format: uuid
        external_ref:
          type: string
          minLength: 1
        assigned_number_id:
          type:
          - string
          - 'null'
          description: phone_number_registry phone_number (E.164) or business_phone_numbers id (uuid).
        agent_id:
          type:
          - string
          - 'null'
          format: uuid
        metadata:
          type: object
          additionalProperties: true
        touches:
          type: array
          minItems: 1
          items:
            $ref: '#/$defs/communicationTouch'
      $defs:
        communicationTouch:
          type: object
          additionalProperties: false
          required:
          - touch_id
          - channel
          - target
          - scheduled_at
          properties:
            touch_id:
              type: string
              minLength: 1
            channel:
              type: string
              enum:
              - call
              - sms
            target:
              type: object
              additionalProperties: false
              required:
              - phone
              properties:
                phone:
                  type: string
                  minLength: 1
                lead_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                name:
                  type:
                  - string
                  - 'null'
                email:
                  type:
                  - string
                  - 'null'
                  format: email
                timezone:
                  type:
                  - string
                  - 'null'
                state:
                  type:
                  - string
                  - 'null'
            scheduled_at:
              type: string
              format: date-time
            timing_window:
              type:
              - object
              - 'null'
              additionalProperties: false
              properties:
                not_before:
                  type:
                  - string
                  - 'null'
                  format: date-time
                not_after:
                  type:
                  - string
                  - 'null'
                  format: date-time
            context:
              type: object
              additionalProperties: true
            metadata:
              type: object
              additionalProperties: true
            message:
              type: string
            sms_category:
              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.