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

# Validate an agent configuration

> Checks a configuration exactly as saving it would, without saving anything. Returns `valid`, every finding with its path, and `resolved`: the configuration with all defaults applied. Pass `agent_id` when the configuration is an edit of an existing agent.

**Scopes:** `agent:read`



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/validate
openapi: 3.1.0
info:
  title: Kallabot API
  version: '2026-11-07'
  description: >
    The Kallabot API lets you build and run AI agents that answer and make phone
    calls and reply on

    WhatsApp, Messenger, Instagram and website chat.


    - **Base URL:** `https://api.kallabot.com`

    - **Auth:** `Authorization: Bearer kb_live_…` (create a key in the dashboard
    under Settings → API keys).
      Each operation lists the scopes its key needs. A workspace key (`kb_live_…`) belongs to the workspace;
      a personal key (`kbp_live_…`) acts as the person who made it, within their role, and is logged under
      their name. Operations marked **Needs a personal key** need someone behind them, so only a personal
      key works there. The browser side of a web call is the exception: its
      `/client` operations take only the session's `X-Webcall-Grant`, so your key never reaches the page.
    - **Errors:** every error is `application/problem+json` with a stable `code`
    ([error reference](https://docs.kallabot.com/developers/errors)).

    - **Retries:** send an `Idempotency-Key` on creates and control actions; a
    retry with the same key never runs twice.

    - **Rate limits:** every response carries `RateLimit-Limit`,
    `RateLimit-Remaining` and `RateLimit-Reset`;
      a `429` carries `Retry-After`.
    - **Versions:** the API is versioned by date. Send `Kallabot-Version:
    2026-11-07` to pin the version
      you built against; without it you get the current version (`2026-11-07`). Every response names the
      version that answered in `Kallabot-Version`, and an unknown version is refused with 400
      `unsupported_api_version`.
    - **Lists:** every list takes `limit` and `cursor` and answers `{data,
    next_cursor, has_more}`. Pass
      `next_cursor` back as `cursor` for the next page; cursors are opaque.
    - **Concurrency:** reads of versioned objects carry an `ETag` (the revision
    in quotes, e.g. `"7"`); send it back as
      `If-Match` and a stale write is refused with 412. Where `If-Match` is marked required, a write without it gets 428.
    - **SDKs:** the official SDKs send `X-Kallabot-SDK`. A deprecated release
    gets a `Kallabot-SDK-Warning` header;
      a release that has been switched off is refused with 426 `sdk_version_unsupported` and must upgrade.
    - **Webhooks:** every event Kallabot sends is listed under Webhooks with its
    payload, signed with
      [Standard Webhooks](https://docs.kallabot.com/developers/webhooks) headers.
  contact:
    name: Kallabot support
    email: contact@kallabot.com
    url: https://docs.kallabot.com
  termsOfService: https://kallabot.com/terms
servers:
  - url: https://api.kallabot.com
    description: Production
security:
  - apiKey: []
tags:
  - name: Agents
    description: >-
      Create, version, publish and archive the AI agents that answer and make
      calls and chats.
  - name: Calls
    description: >-
      Place phone calls, read them back with transcripts, recordings and
      timings, and control live calls.
  - name: Scheduled calls
    description: >-
      Book an outbound call for later; Kallabot dials at the right time in the
      callee's time zone.
  - name: Web calls
    description: Start a voice call from a browser (WebRTC) with a short-lived grant.
  - name: Tools
    description: >-
      Give agents actions: HTTP API tools, MCP servers, and the secrets they
      use.
  - name: Knowledge
    description: Index websites, files and catalogs so agents answer from your own facts.
  - name: Numbers
    description: >-
      Search, buy and configure phone numbers, port numbers in, and choose
      caller IDs.
  - name: SIP trunks
    description: Bring your own carrier over SIP and attach its numbers to agents.
  - name: Inbox
    description: >-
      Read chat threads from WhatsApp, Messenger, Instagram and web chat, and
      manage their state.
  - name: Web chat
    description: Create and publish website chat widgets.
  - name: Webhooks
    description: >-
      Receive signed events when calls end, messages arrive and more; inspect
      and replay deliveries.
  - name: Minutes
    description: Read the workspace's minutes and move them between the pool and people.
  - name: Billing
    description: >-
      See the plan, prices and invoices; open Checkout or the billing portal,
      sync seats and set auto top-up. Money is integer minor units plus
      `currency`.
paths:
  /v1/agents/validate:
    post:
      tags:
        - Agents
      summary: Validate an agent configuration
      description: >-
        Checks a configuration exactly as saving it would, without saving
        anything. Returns `valid`, every finding with its path, and `resolved`:
        the configuration with all defaults applied. Pass `agent_id` when the
        configuration is an edit of an existing agent.


        **Scopes:** `agent:read`
      operationId: validateAgent
      parameters:
        - name: Kallabot-Version
          in: header
          required: false
          description: >-
            The API version to answer as, a date (`YYYY-MM-DD`). Leave it out
            for the current version (`2026-11-07`). An unknown version is
            refused with 400 `unsupported_api_version`.
          schema:
            type: string
            enum:
              - '2026-11-07'
            example: '2026-11-07'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateResponse'
          headers:
            RateLimit-Limit:
              description: Requests allowed per minute for this credential.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window is full again.
              schema:
                type: integer
            X-Request-Id:
              description: Quote this when contacting support.
              schema:
                type: string
            Kallabot-Version:
              description: The API version that answered this request.
              schema:
                type: string
                example: '2026-11-07'
            Kallabot-SDK-Warning:
              description: >-
                Sent when the SDK release that made the request is deprecated:
                what to upgrade to. The SDKs log it once.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/UnsupportedApiVersion'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/InvalidRequest'
        '426':
          $ref: '#/components/responses/SdkVersionUnsupported'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey: []
components:
  schemas:
    ValidateRequest:
      properties:
        config:
          $ref: '#/components/schemas/AgentSpec'
        agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Agent Id
          description: >-
            The agent this config is an edit of. A knowledge source it already
            attaches that has since been deleted from the library is then
            dropped with a warning, as saving it would; without it, such an id
            is refused like any unknown one.
      additionalProperties: false
      type: object
      required:
        - config
      title: ValidateRequest
    ValidateResponse:
      properties:
        valid:
          type: boolean
          title: Valid
        config_hash:
          type: string
          title: Config Hash
        findings:
          items:
            $ref: '#/components/schemas/ValidationFinding'
          type: array
          title: Findings
        resolved:
          additionalProperties: true
          type: object
          title: Resolved
          description: >-
            The configuration with every server default applied — what would be
            saved.
      type: object
      required:
        - valid
        - config_hash
        - findings
        - resolved
      title: ValidateResponse
    AgentSpec:
      properties:
        name:
          type: string
          title: Name
          default: Inline agent
        prompt:
          type: string
          title: Prompt
          description: >-
            The agent's persona, task and rules. The voice envelope is added
            automatically.
          default: You are a friendly voice assistant on a phone call.
        greeting:
          anyOf:
            - type: string
            - type: 'null'
          title: Greeting
          description: >-
            Spoken on answer. With greeting_mode 'fixed' this exact text is
            used; with 'dynamic' it is the brief the model opens from. Null
            always generates.
          default: Hi! How can I help?
        outbound_greeting:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Greeting
          description: >-
            Spoken instead of `greeting` on calls the agent places. The first
            line sets the role the model keeps playing: an inbound caller who
            hears an outbound opener gets 'thanks for picking up' next. Empty
            uses `greeting` for both directions.
        purpose:
          anyOf:
            - type: string
              maxLength: 300
            - type: 'null'
          title: Purpose
          description: >-
            Why the agent places outbound calls, written the way it would say it
            ("you're calling from the Dubai property desk to see if they're
            looking to buy or rent"). Told only on calls the agent places, so it
            can answer "why are you calling me?" honestly; a `purpose` call
            variable overrides it per call. Empty: a plain follow-up from the
            business.
        greeting_mode:
          anyOf:
            - type: string
              enum:
                - fixed
                - dynamic
            - type: 'null'
          title: Greeting Mode
          description: >-
            fixed (default): the same words every call — one round trip faster,
            and the caller hears audio sooner. dynamic: the model writes the
            opener from `greeting` as a brief plus who is calling and why, so a
            repeat caller is not greeted like a stranger. Costs one inference
            before the first word.
        language:
          type: string
          title: Language
          default: en
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: IANA zone used when the agent says the time.
        stt:
          $ref: '#/components/schemas/STTConfig'
        llm:
          $ref: '#/components/schemas/LLMConfig'
        tts:
          $ref: '#/components/schemas/TTSConfig'
        turn:
          $ref: '#/components/schemas/TurnConfig'
        style:
          $ref: '#/components/schemas/StyleConfig'
        audio:
          $ref: '#/components/schemas/AudioConfig'
        call:
          $ref: '#/components/schemas/CallConfig'
        memory:
          anyOf:
            - $ref: '#/components/schemas/MemoryConfig'
            - type: 'null'
        knowledge:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeConfig'
            - type: 'null'
        tools:
          items:
            $ref: '#/components/schemas/ToolConfig'
          type: array
          title: Tools
        builtins:
          anyOf:
            - $ref: '#/components/schemas/BuiltinsConfig'
            - type: 'null'
        analysis:
          anyOf:
            - $ref: '#/components/schemas/AnalysisConfig'
            - type: 'null'
        web_search:
          anyOf:
            - $ref: '#/components/schemas/WebSearchConfig'
            - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Your own data. Echoed back on every call record.
      additionalProperties: false
      type: object
      title: AgentSpec
      description: A complete agent. Every field optional.
    ValidationFinding:
      properties:
        severity:
          type: string
          enum:
            - error
            - warning
            - info
          title: Severity
          description: '`error` blocks publishing; the others don''t.'
        code:
          type: string
          title: Code
          description: A stable machine code for the finding.
        path:
          type: string
          title: Path
          description: JSON Pointer to the field in `config` it is about.
        message:
          type: string
          title: Message
          description: What is wrong, in plain words.
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: The voice or model provider it concerns, if any.
      type: object
      required:
        - severity
        - code
        - path
        - message
      title: ValidationFinding
    Problem:
      type: object
      description: >-
        An RFC 9457 problem. `code` is the stable contract; `title` and `detail`
        are for people.
      required:
        - type
        - title
        - status
        - code
        - retryable
      properties:
        type:
          type: string
          format: uri
          example: https://docs.kallabot.com/errors/not_found
        title:
          type: string
          example: Agent not found
        status:
          type: integer
          example: 404
        code:
          type: string
          example: not_found
        detail:
          type: string
          example: Agent does not exist, or you do not have access to it.
        retryable:
          type: boolean
          example: false
        field_problems:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: JSON Pointer to the field.
                example: /to
              code:
                type: string
                example: missing
              message:
                type: string
                example: Field required
        request_id:
          type: string
          example: req_01HZX3K9Q2
    STTConfig:
      properties:
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: soniox | deepgram
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: See GET /v1/providers for valid ids.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: ISO code, e.g. 'en'. Single language is most accurate.
        languages:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Languages
          description: Additional expected languages. Multiple languages reduce robustness.
        strict_language:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict Language
          description: >-
            Confine output to the languages above. Fixes accented English coming
            back transliterated into another script. Strongly recommended.
        context:
          anyOf:
            - $ref: '#/components/schemas/SonioxContext'
            - type: 'null'
        language_identification:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Language Identification
          description: >-
            Soniox: tag every word with the language it was spoken in. On by
            default; this is what lets a caller switch languages mid-sentence.
        language_focus:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Language Focus
          description: >-
            Soniox: once the caller's language is clear, narrow the hints to it.
            Off by default — narrowing turns anyone else's language (an Urdu
            side conversation on an English call) into wrong-script English.
        voice_focus:
          anyOf:
            - type: string
              enum:
                - near-field
                - far-field
            - type: 'null'
          title: Voice Focus
          description: >-
            AssemblyAI: isolate the primary voice. near-field for
            handsets/headsets.
        mode:
          anyOf:
            - type: string
              enum:
                - min_latency
                - balanced
                - max_accuracy
            - type: 'null'
          title: Mode
          description: AssemblyAI U3 Pro latency/accuracy preset (server default balanced).
        endpointing:
          anyOf:
            - $ref: '#/components/schemas/Endpointing'
            - type: 'null'
        diarization:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Diarization
          description: >-
            Label every word with who said it. Soniox supports up to 15 speakers
            and returns a per-token speaker id. Required for `addressivity`.
            Note the provider's own caveat: real-time diarization is less
            accurate than batch, and provider endpointing degrades it further —
            so pair this with turn.strategy 'semantic' or 'smart_turn', never
            'provider'.
        addressivity:
          anyOf:
            - type: string
              enum:
                - 'off'
                - retain
                - ignore
            - type: 'null'
          title: Addressivity
          description: >-
            What to do when speech reaches us that was not aimed at the agent.
            retain (default): the agent stays silent but the line is kept in
            context, so it can pick it up later ('did your friend want one
            too?'). ignore: dropped entirely. off: everything becomes a turn —
            the agent answers the room. Works with or without diarization; the
            acoustic read below is the stronger signal and stands alone.
          default: retain
        perception:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Perception
          description: >-
            Read emotion and non-verbal events (laughter, crying, coughing) from
            the audio with a locally-hosted SenseVoiceSmall model, and describe
            them to the language model. Runs on a side channel during
            speech-recognition finalisation and is dropped if it is not ready in
            time, so it never delays a reply. Off unless the model is installed.
        speaker_embeddings:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Speaker Embeddings
          description: >-
            Experimental local call-scoped speaker embeddings. Requires a
            calibrated sherpa-onnx model; off until real multi-speaker threshold
            tests pass.
          default: false
        speaker_embedding_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Speaker Embedding Model
          description: Path to a sherpa-onnx speaker embedding ONNX model.
        speaker_embedding_threshold:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Speaker Embedding Threshold
          description: >-
            Cosine/manager match threshold after calibration; library example
            defaults to 0.6.
        acoustics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Acoustics
          description: >-
            Judge whether speech was aimed at the agent from how it sounded, not
            only from who said it. Level and spectral tilt, measured against a
            rolling baseline of this caller on this call, separate 'shouted to
            someone across the room' (louder, but dull, because off-axis speech
            loses its highs) from 'said emphatically into the phone' (louder,
            and bright). This is what catches the caller turning to talk to
            someone else — diarization cannot, because it is the same speaker.
            Costs no extra provider calls.
          default: true
        clarify_below:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Clarify Below
          description: >-
            When average recognition confidence falls below this, the agent is
            told the words are unreliable and asked to request a repeat rather
            than answer them. This is what stops it confidently confirming a
            misheard address. ~0.65 is a reasonable start. 0 (default) disables.
        ignore_below:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Ignore Below
          description: >-
            Below this, an utterance is treated as background and the agent
            stays silent — nobody was talking to it. Must be lower than
            clarify_below; ~0.40 catches a voice across the room. Note the
            difference: below ignore_below the agent says nothing, between the
            two floors it asks you to repeat. 0 (default) disables.
        keywords:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Keywords
          description: 'Deepgram only: term boosting.'
      type: object
      title: STTConfig
    LLMConfig:
      properties:
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: telnyx | openai (LLM inference)
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
        max_tokens:
          anyOf:
            - type: integer
              maximum: 4096
              minimum: 1
            - type: 'null'
          title: Max Tokens
          description: Cap replies. A voice reply rarely needs more than 300.
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
        frequency_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Frequency Penalty
        presence_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Presence Penalty
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
          description: Reproducible sampling where the provider supports it.
        extra:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra
          description: >-
            Provider-specific passthrough, e.g. {"reasoning_effort": "none"} on
            Telnyx DeepSeek.
          examples:
            - reasoning_effort: none
        fallback:
          anyOf:
            - $ref: '#/components/schemas/LLMFallback'
            - type: 'null'
          description: >-
            Where a turn goes when this model rate-limits, errors or stalls, in
            the same turn. Unset: the platform's failover model.
      type: object
      title: LLMConfig
    TTSConfig:
      properties:
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: inworld | cartesia
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
          description: Provider voice id.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        speed:
          anyOf:
            - type: number
              maximum: 1.5
              minimum: 0.6
            - type: 'null'
          title: Speed
          description: Cartesia generation speed multiplier. 1.0 is native speed.
        volume:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0.5
            - type: 'null'
          title: Volume
          description: Cartesia generation volume multiplier. Default 1.0.
        delivery_mode:
          anyOf:
            - type: string
              enum:
                - STABLE
                - BALANCED
                - CREATIVE
            - type: 'null'
          title: Delivery Mode
          description: >-
            Inworld TTS-2 only. STABLE tracks the text exactly; CREATIVE varies
            more.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Inworld only.
        stability:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Stability
          description: >-
            ElevenLabs only. Lower is more expressive and varied, higher more
            consistent (0.5 default).
        emotion:
          anyOf:
            - type: string
            - type: 'null'
          title: Emotion
          description: >-
            Cartesia baseline emotion, English voices only (beta). Sonic 3.6
            supports 60+ values; primary production choices are neutral, calm,
            content, sad, scared and angry.
        pronunciation_dict_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Pronunciation Dict Id
          description: Cartesia pronunciation dictionary applied to every request.
        max_buffer_delay_ms:
          anyOf:
            - type: integer
              maximum: 5000
              minimum: 0
            - type: 'null'
          title: Max Buffer Delay Ms
          description: >-
            Cartesia server-side text buffering. Use 0 with Kallabot sentence
            aggregation so two buffering layers do not stack latency.
        steering:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Steering
          description: >-
            Let the LLM write inline [direction] tags that the voice performs.
            Enabled by default on models that support it.
        non_verbals:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Non Verbals
          description: >-
            Allow [laugh], [sigh] and similar. Off by default — reads as
            unprofessional on support calls.
        backchanneling:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Backchanneling
          description: >-
            Permit brief acknowledgements while the caller holds a long speaking
            turn.
        backchannel_start_delay_sec:
          anyOf:
            - type: number
              maximum: 20
              minimum: 1
            - type: 'null'
          title: Backchannel Start Delay Sec
        backchannel_gap_sec:
          anyOf:
            - type: number
              maximum: 30
              minimum: 2
            - type: 'null'
          title: Backchannel Gap Sec
        backchannel_max_per_minute:
          anyOf:
            - type: integer
              maximum: 6
              minimum: 1
            - type: 'null'
          title: Backchannel Max Per Minute
        backchannel_mode:
          anyOf:
            - type: string
              enum:
                - neutral
                - contextual
            - type: 'null'
          title: Backchannel Mode
      type: object
      title: TTSConfig
    TurnConfig:
      properties:
        strategy:
          anyOf:
            - type: string
              enum:
                - semantic
                - smart_turn
                - provider
            - type: 'null'
          title: Strategy
          description: >-
            semantic (default): Smart Turn listens to the waveform and the LLM
            then judges whether the thought was actually finished, emitting a
            hidden ✓/○/◐ marker. On ○ or ◐ the reply is withheld and the caller
            keeps the floor — this is what stops the agent answering 'my number
            is four one five...' mid-sequence. smart_turn: the acoustic model
            alone; one less judgement, slightly cheaper, and it will cut a slow
            speaker off. provider: Soniox's own semantic endpointing, no local
            compute, and the only option with numeric sensitivity controls. All
            three are mutually exclusive.
        max_wait_sec:
          anyOf:
            - type: number
              maximum: 10
              minimum: 0.6
            - type: 'null'
          title: Max Wait Sec
          description: >-
            Backstop for when the turn model never reaches a confident verdict.
            Default 0.7 on semantic turns (the LLM still holds a half line) and
            1.2 otherwise. This is NOT the turn timer, but it is not free
            either: when the model cannot decide, the caller waits this long in
            silence. Raising it makes an undecided turn read as a dropped call;
            lowering it below about a second makes the agent interrupt people.
        pre_speech_ms:
          anyOf:
            - type: integer
              maximum: 2000
              minimum: 0
            - type: 'null'
          title: Pre Speech Ms
          description: >-
            Audio kept from before VAD noticed speech. Default 500. The turn
            model reads onset prosody; starve it and it misjudges clipped
            openings.
        claim_secs:
          anyOf:
            - type: number
              maximum: 1.5
              minimum: 0.2
            - type: 'null'
          title: Claim Secs
          description: >-
            While the agent is speaking, how long caller speech must continue
            before it claims the floor. Default 0.45: brief acknowledgements do
            not interrupt, while a real barge-in is respected before it feels
            talked over.
        ringback_settle_sec:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0.1
            - type: 'null'
          title: Ringback Settle Sec
          description: >-
            When protect_greeting is enabled, how long after our opening audio
            starts before carrier leakage is no longer muted. Default 0.6.
        resume_short_sec:
          anyOf:
            - type: number
              maximum: 30
              minimum: 0.5
            - type: 'null'
          title: Resume Short Sec
          description: >-
            semantic only. After ○ (cut off mid-sentence), sit silent this long
            waiting for them to carry on, then hand the floor back. Default 1.5.
        resume_long_sec:
          anyOf:
            - type: number
              maximum: 60
              minimum: 0.5
            - type: 'null'
          title: Resume Long Sec
          description: >-
            Deprecated compatibility field. ◐ side-talk/hold turns now remain
            silent until the caller resumes; automatic check-ins felt intrusive.
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: VAD speech-detection threshold. Default 0.65.
        min_volume:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Min Volume
          description: >-
            Below this, audio is not treated as speech. Default 0.30; the
            library default of 0.60 discards ordinary speech.
        stop_secs:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0.1
            - type: 'null'
          title: Stop Secs
          description: >-
            Silence before VAD reports the caller stopped. Default 0.20. This is
            not the same as deciding the caller has finished — Smart Turn and
            the completion model do that — so raising it mostly adds latency to
            every turn and shrinks the window Smart Turn has to wait for the
            final transcript. Bounded at 1.0s for that reason.
        interruptible:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Interruptible
          description: Can the caller talk over the agent. Default true.
        min_interrupt_words:
          anyOf:
            - type: integer
              maximum: 10
              minimum: 1
            - type: 'null'
          title: Min Interrupt Words
          description: >-
            While the agent is speaking, ignore anything shorter than this many
            words. 2 is the useful value: it treats 'mm-hm', 'yeah' and 'right'
            as agreement rather than interruption, so an agent reading back an
            address is not chopped into fragments. Costs nothing on a normal
            turn.
        protect_greeting:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Protect Greeting
          description: >-
            Ignore caller audio until the greeting finishes. Carriers leak
            ringback and the caller's own 'hello?' into the first second of
            media, which otherwise truncates the opening line.
        idle_timeout_sec:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 0
            - type: 'null'
          title: Idle Timeout Sec
          description: Silence before the agent prompts the caller. 0 disables.
      type: object
      title: TurnConfig
      description: When the caller is considered to have finished speaking.
    StyleConfig:
      properties:
        disfluency:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disfluency
          description: >-
            Default true. Allow fillers, false starts, thinking noises and
            self-correction. Clean, perfectly-formed sentences every turn read
            as synthetic even when the voice is flawless.
        avoid_tells:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Avoid Tells
          description: >-
            Default true. Forbid the behaviours that instantly reveal a machine:
            reading code or URLs aloud, listing six options in one breath, 'Is
            there anything else I can help you with today?', and claiming to be
            human when asked directly.
        prompt_mode:
          anyOf:
            - type: string
              enum:
                - full
                - lean
            - type: 'null'
          title: Prompt Mode
          description: >-
            Default lean: the platform's short hidden guidance and turn
            protocol. full: the longer guidance it replaced on 31 Oct 2026, kept
            for comparison.
        backchanneling:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Backchanneling
        backchannel_mode:
          anyOf:
            - type: string
              enum:
                - neutral
                - contextual
            - type: 'null'
          title: Backchannel Mode
        backchannel_start_delay_sec:
          anyOf:
            - type: number
              maximum: 20
              minimum: 1
            - type: 'null'
          title: Backchannel Start Delay Sec
        backchannel_gap_sec:
          anyOf:
            - type: number
              maximum: 30
              minimum: 2
            - type: 'null'
          title: Backchannel Gap Sec
          description: >-
            Seconds between two listener sounds ("mm-hm", "oh nice"). Default
            3.5.
        backchannel_max_per_minute:
          anyOf:
            - type: integer
              maximum: 10
              minimum: 1
            - type: 'null'
          title: Backchannel Max Per Minute
          description: Most listener sounds in any 60 seconds. Default 6.
        lookup_cut_in:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Lookup Cut In
          description: >-
            Default false. When a lookup's answer lands while the caller is
            still talking, the agent takes the floor at their next pause instead
            of waiting for the end of their turn.
      type: object
      title: StyleConfig
      description: >-
        How human the agent is allowed to sound.


        Both default on. Turn them off for a compliance read-out or a menu bot,

        where a flat, identical delivery every time is the requirement rather
        than

        the flaw.
    AudioConfig:
      properties:
        noise_suppression:
          anyOf:
            - type: string
              enum:
                - auto
                - none
                - rnnoise
                - koala
                - krisp
                - aic
            - type: 'null'
          title: Noise Suppression
          description: >-
            Applied to inbound caller audio. auto (the default) uses ai-coustics
            Quail (speech cleaned for STT, not for ears) when AIC_LICENSE_KEY is
            set, else Krisp VIVA when installed, else nothing. rnnoise is free
            and local but tuned for human ears, and can cost speech recognition
            accuracy.
        crowded_places:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Crowded Places
          description: >-
            With Krisp, also remove other people's voices, not just noise. For
            malls and open-plan offices. It weakens the agent's sense of who
            else is in the room, so it is off by default.
        ambient:
          anyOf:
            - $ref: '#/components/schemas/AmbientConfig'
            - type: 'null'
          description: >-
            Background bed under the agent's own audio, so silence does not
            sound dead.
        wideband:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Wideband
          description: >-
            Browser calls only: send the agent's voice at 16 kHz instead of
            phone-like 8 kHz. Phone calls run at the trunk's G.711 rate.
      type: object
      title: AudioConfig
    CallConfig:
      properties:
        direction:
          anyOf:
            - type: string
              enum:
                - inbound
                - outbound
                - both
            - type: 'null'
          title: Direction
          description: >-
            Where this agent may be used. Phone-number routing remains a
            separate resource.
        max_duration_sec:
          anyOf:
            - type: integer
              maximum: 7200
              minimum: 10
            - type: 'null'
          title: Max Duration Sec
        record:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Record
        summarize_long_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Summarize Long Calls
          description: >-
            Default true. On a call long enough to outgrow the model's window,
            compress the older turns into a summary and keep the recent ones
            verbatim, instead of the agent forgetting the caller's name.
        end_call:
          anyOf:
            - type: boolean
            - type: 'null'
          title: End Call
          description: >-
            Default true. The agent may hang up once the conversation is over
            (goodbye said, opt-out, next step agreed), after its goodbye plays.
        voicemail:
          anyOf:
            - $ref: '#/components/schemas/VoicemailConfig'
            - type: 'null'
        transfer:
          anyOf:
            - $ref: '#/components/schemas/TransferConfig'
            - type: 'null'
        monitoring_notice:
          anyOf:
            - $ref: '#/components/schemas/MonitoringNotice'
            - type: 'null'
      type: object
      title: CallConfig
    MemoryConfig:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
        scope:
          anyOf:
            - type: string
              enum:
                - caller
                - agent
            - type: 'null'
          title: Scope
          description: 'caller: remembered per phone number across calls.'
        retention_days:
          anyOf:
            - type: integer
              maximum: 3650
              minimum: 1
            - type: 'null'
          title: Retention Days
      type: object
      title: MemoryConfig
    KnowledgeConfig:
      properties:
        ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ids
          description: Knowledge base ids to search.
        top_k:
          anyOf:
            - type: integer
              maximum: 20
              minimum: 1
            - type: 'null'
          title: Top K
        mode:
          anyOf:
            - type: string
              enum:
                - auto
                - prompt
                - search
            - type: 'null'
          title: Mode
          description: >-
            auto (default): libraries up to about 1,500 tokens go whole into the
            instructions, larger ones are searched each turn. prompt: always
            whole. search: always searched.
        channels:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                  enum:
                    - phone
                    - web
                    - whatsapp
                    - instagram
                    - messenger
                    - web_chat
                type: array
              type: object
            - type: 'null'
          title: Channels
          description: >-
            Per source id, the channels it answers on. A source not listed
            answers on every channel; an empty list switches it off everywhere
            without detaching it.
      type: object
      title: KnowledgeConfig
    ToolConfig:
      properties:
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Id
          description: The saved tool (POST /v1/tools).
        kind:
          anyOf:
            - type: string
              enum:
                - api
                - mcp_server
                - google_sheets
            - type: 'null'
          title: Kind
          description: Server-set from the saved tool.
        channels:
          anyOf:
            - items:
                type: string
                enum:
                  - phone
                  - web
                  - whatsapp
                  - instagram
                  - messenger
                  - web_chat
              type: array
              maxItems: 6
            - type: 'null'
          title: Channels
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: 'null'
          title: Allowed Tools
        overrides:
          anyOf:
            - $ref: '#/components/schemas/ToolOverrides'
            - type: 'null'
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        method:
          anyOf:
            - type: string
              enum:
                - GET
                - POST
                - PUT
                - PATCH
                - DELETE
            - type: 'null'
          title: Method
        transport:
          anyOf:
            - type: string
              enum:
                - sse
                - streamable_http
            - type: 'null'
          title: Transport
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Headers
        auth:
          anyOf:
            - $ref: '#/components/schemas/ToolAuth'
            - type: 'null'
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters
        timeout_ms:
          anyOf:
            - type: integer
              maximum: 30000
              minimum: 100
            - type: 'null'
          title: Timeout Ms
        blocking:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Blocking
        filler:
          anyOf:
            - type: string
            - type: 'null'
          title: Filler
      type: object
      title: ToolConfig
      description: |-
        A saved tool (``POST /v1/tools``) attached to this agent.

        The agent keeps the reference only. The tool's definition and its
        credential are read when a call starts or a reply is written, so editing
        a tool or rotating its key reaches the next conversation without a
        republish, and no URL, header or secret is ever stored in an agent
        version. Every invocation is recorded in ``tool_invocation``.

        ``channels`` narrows where the agent may use it (default: everywhere the
        tool can run; Google Sheets tools run in chats only). ``allowed_tools``
        picks an MCP server's tools, within the server's own ceiling; without it
        every tool the server doesn't mark destructive is offered.

        The inline fields below are read from documents saved before tools were
        references, and are ignored.
    BuiltinsConfig:
      properties:
        knowledge_search:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Knowledge Search
        calendar:
          anyOf:
            - $ref: '#/components/schemas/CalendarBuiltin'
            - type: 'null'
        sheets:
          anyOf:
            - $ref: '#/components/schemas/SheetsBuiltin'
            - type: 'null'
        whatsapp_send:
          anyOf:
            - $ref: '#/components/schemas/WhatsAppSendBuiltin'
            - type: 'null'
        email_send:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Email Send
      additionalProperties: false
      type: object
      title: BuiltinsConfig
      description: >-
        Built-in abilities beyond transfer (`call.transfer`), hanging up

        (`call.end_call`) and web search (`web_search`), which keep their
        blocks.
    AnalysisConfig:
      properties:
        successDefinition:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Successdefinition
        dispositionLabels:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Dispositionlabels
        bookingToolIds:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Bookingtoolids
        extractFields:
          anyOf:
            - items:
                $ref: '#/components/schemas/ExtractField'
              type: array
              maxItems: 20
            - type: 'null'
          title: Extractfields
      additionalProperties: false
      type: object
      title: AnalysisConfig
      description: >-
        What the post-conversation analysis looks for (W2-A's job reads the
        compiled block).
    WebSearchConfig:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
        max_results:
          type: integer
          maximum: 10
          minimum: 1
          title: Max Results
          default: 5
        domains:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Domains
          description: Optional public-domain allowlist. Hostnames only, no URLs.
        max_per_call:
          type: integer
          maximum: 10
          minimum: 1
          title: Max Per Call
          description: Most searches the agent may run in one call or one chat reply.
          default: 3
        provider:
          anyOf:
            - type: string
              pattern: ^[a-z][a-z0-9_]{1,31}$
            - type: 'null'
          title: Provider
          description: >-
            A search provider that passed the eval gate (GET
            /v1/search/providers); default: the platform's (Telnyx).
      type: object
      title: WebSearchConfig
      description: >-
        `search_web`, the tool the agent calls itself when it needs something
        current or outside the

        business (founder override #3: no feeds, no router; the agent searches
        for itself).
    SonioxContext:
      properties:
        general:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: General
          description: >-
            Short key/value facts: domain, topic, business name, location. Ten
            or fewer.
          examples:
            - domain: Dental clinic
              location: Dubai
              setting: Phone booking
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Longer background prose. Less influential than general or terms.
        terms:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Terms
          description: 'Words to expect: product names, staff names, medications, jargon.'
          examples:
            - - Invisalign
              - Dr Al Mansouri
              - root canal
      type: object
      title: SonioxContext
      description: >-
        Domain context. The single largest accuracy lever Soniox exposes.


        Telling the model what the call is about, and which words to expect,
        fixes

        the class of error where a name or product comes back as a
        similar-sounding

        common word. Capped at 8,000 tokens by the provider.
    Endpointing:
      properties:
        latency_level:
          anyOf:
            - type: integer
              maximum: 3
              minimum: 0
            - type: 'null'
          title: Latency Level
          description: >-
            0 default, 3 most aggressive. Higher finalises sooner and may split
            long speech.
        sensitivity:
          anyOf:
            - type: number
              maximum: 1
              minimum: -1
            - type: 'null'
          title: Sensitivity
          description: >-
            Higher makes endpoints more likely. Negative helps slow speakers who
            pause mid-sentence.
        max_delay_ms:
          anyOf:
            - type: integer
              maximum: 3000
              minimum: 500
            - type: 'null'
          title: Max Delay Ms
          description: >-
            Hard upper bound on endpoint latency after speech stops. Provider
            default 2000.
      type: object
      title: Endpointing
      description: >-
        Soniox semantic endpointing.


        Only honoured when ``turn.strategy = "provider"``. With the default

        ``smart_turn`` strategy Pipecat disables provider endpointing entirely,
        and

        these fields are inert.
    LLMFallback:
      properties:
        provider:
          type: string
          title: Provider
          description: baseten | telnyx | openai. Never groq or cerebras.
        model:
          type: string
          title: Model
          description: A model from GET /v1/providers on that provider.
      additionalProperties: false
      type: object
      required:
        - provider
        - model
      title: LLMFallback
      description: >-
        The model a turn fails over to when the agent's own model errors or
        stalls.
    AmbientConfig:
      properties:
        file:
          anyOf:
            - type: string
              enum:
                - office
                - call-center
                - restaurant
                - saloon
                - waiting-room
                - room
            - type: 'null'
          title: File
          description: >-
            Named background bed (60 s loops; 'room' is a short one). Perfect
            silence between sentences is the clearest tell that a caller is
            talking to software; a real person is never in an anechoic chamber.
        volume:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Volume
          description: >-
            Default 0.10. Above ~0.15 it competes with the voice and the far-end
            STT works harder.
      type: object
      title: AmbientConfig
    VoicemailConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: >-
            Default false. On calls the agent places, wait for a
            person-or-machine verdict before speaking; on a machine, leave
            `message` and hang up.
          default: false
        message:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Message
          description: Spoken once the voicemail greeting ends. Required when enabled.
      additionalProperties: false
      type: object
      title: VoicemailConfig
      description: >-
        Outbound phone calls only: tell a person from an answering machine
        before speaking.
    TransferConfig:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
        destinations:
          items:
            $ref: '#/components/schemas/TransferDestination'
          type: array
          maxItems: 20
          title: Destinations
        failure_message:
          anyOf:
            - type: string
              maxLength: 280
            - type: 'null'
          title: Failure Message
      type: object
      title: TransferConfig
    MonitoringNotice:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          description: >-
            Default false. Say a short notice before the greeting that the call
            may be recorded or monitored (where listen-in or take-over needs
            callers told).
        text:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Text
          description: >-
            The notice in your own words. Empty: a plain default in the agent's
            language.
      type: object
      title: MonitoringNotice
    ToolOverrides:
      properties:
        filler:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Filler
          description: Said if the tool is still running after filler_after_ms.
        filler_after_ms:
          anyOf:
            - type: integer
              maximum: 10000
              minimum: 0
            - type: 'null'
          title: Filler After Ms
        timeout_ms:
          anyOf:
            - type: integer
              maximum: 30000
              minimum: 100
            - type: 'null'
          title: Timeout Ms
      additionalProperties: false
      type: object
      title: ToolOverrides
      description: What this agent changes about a saved tool, for itself only.
    ToolAuth:
      properties:
        type:
          type: string
          enum:
            - none
            - bearer
            - header
            - basic
            - query
            - credential
          title: Type
          default: none
        credential_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Credential Id
          description: A saved credential (/v1/tool-credentials) when type is 'credential'.
        token:
          anyOf:
            - type: string
            - type: 'null'
          title: Token
          description: Bearer token or basic credentials. Write-only.
        header:
          anyOf:
            - type: string
            - type: 'null'
          title: Header
          description: Header name when type is 'header'.
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: Query parameter name when type is 'query'.
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Header or query value. Write-only.
        sealed:
          anyOf:
            - type: string
            - type: 'null'
          title: Sealed
          description: >-
            Server-set. AES-256-GCM ciphertext of token/value. Never accepted
            from a client.
        hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Hint
          description: Server-set. Last 4 characters, for display.
      type: object
      title: ToolAuth
      description: |-
        How the tool authenticates to its own endpoint.

        ``token``/``value`` are write-only: a client sends plaintext here when
        creating or editing a tool, and the server moves it into a sealed
        ``tool_credential`` (``kallabot.services.tools``); the tool keeps only
        ``{type: 'credential', credential_id}``. Nothing that reads a tool back
        carries the secret; the credential shows a hint (last four characters).
    CalendarBuiltin:
      properties:
        google_connection_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Google Connection Id
        calendar_id:
          type: string
          maxLength: 256
          minLength: 1
          title: Calendar Id
          default: primary
        timezone:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Timezone
          description: 'Default: the agent''s timezone.'
        duration_min:
          type: integer
          maximum: 480
          minimum: 5
          title: Duration Min
          description: How long one appointment is.
          default: 30
        hours:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/OpeningHours'
                  - type: 'null'
              type: array
              maxItems: 7
              minItems: 7
            - type: 'null'
          title: Hours
          description: >-
            Bookable hours Monday..Sunday; null for a closed day. Default
            Mon–Fri 09:00–18:00.
        min_notice_min:
          type: integer
          maximum: 10080
          minimum: 0
          title: Min Notice Min
          description: Earliest booking, in minutes from now.
          default: 60
      additionalProperties: false
      type: object
      required:
        - google_connection_id
      title: CalendarBuiltin
      description: >-
        Check free times and book on a connected Google Calendar
        (`check_availability`, `book_appointment`).
    SheetsBuiltin:
      properties:
        google_connection_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Google Connection Id
        spreadsheet_id:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,128}$
          title: Spreadsheet Id
        sheet:
          type: string
          maxLength: 100
          title: Sheet
          description: Tab name; empty = the first tab.
          default: ''
        when:
          type: string
          maxLength: 300
          title: When
          description: When to look something up, e.g. 'stock or prices'.
          default: ''
      additionalProperties: false
      type: object
      required:
        - google_connection_id
        - spreadsheet_id
      title: SheetsBuiltin
      description: >-
        Look rows up in a Google Sheet the business keeps (`look_up_sheet`).
        Saving rows is a saved

        `google_sheets` tool attached to the agent.
    WhatsAppSendBuiltin:
      properties:
        connection_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Connection Id
      additionalProperties: false
      type: object
      required:
        - connection_id
      title: WhatsAppSendBuiltin
    ExtractField:
      properties:
        key:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Key
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
            - phone
            - email
          title: Type
          default: string
        description:
          type: string
          maxLength: 300
          title: Description
          default: ''
      additionalProperties: false
      type: object
      required:
        - key
      title: ExtractField
    TransferDestination:
      properties:
        id:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_-]*$
          title: Id
          description: Stable identifier selected by the model. Never a phone number.
        label:
          type: string
          maxLength: 80
          minLength: 1
          title: Label
        to:
          type: string
          pattern: ^\+[1-9]\d{7,14}$
          title: To
          description: Approved E.164 destination.
        mode:
          type: string
          enum:
            - cold
            - warm
          title: Mode
          default: cold
        description:
          type: string
          maxLength: 280
          minLength: 1
          title: Description
          description: When this named destination should be selected.
        caller_message:
          anyOf:
            - type: string
              maxLength: 280
            - type: 'null'
          title: Caller Message
        consultation_message:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Consultation Message
        timeout_sec:
          type: integer
          maximum: 60
          minimum: 10
          title: Timeout Sec
          default: 30
      type: object
      required:
        - id
        - label
        - to
        - description
      title: TransferDestination
    OpeningHours:
      properties:
        start:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          title: Start
        end:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          title: End
      additionalProperties: false
      type: object
      required:
        - start
        - end
      title: OpeningHours
      description: One weekday's bookable hours, local time ("09:00"–"18:00").
  responses:
    UnsupportedApiVersion:
      description: Kallabot-Version names a version this API doesn't have
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/unsupported_api_version
            title: Kallabot-Version names a version this API doesn't have
            status: 400
            code: unsupported_api_version
            retryable: false
    Unauthenticated:
      description: Missing or invalid API key
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/unauthenticated
            title: Missing or invalid API key
            status: 401
            code: unauthenticated
            retryable: false
    Forbidden:
      description: The key lacks a required scope
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/insufficient_scope
            title: The key lacks a required scope
            status: 403
            code: insufficient_scope
            retryable: false
    Conflict:
      description: Conflicts with the resource's current state
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/revision_conflict
            title: Conflicts with the resource's current state
            status: 409
            code: revision_conflict
            retryable: false
    InvalidRequest:
      description: One or more fields are not valid
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/invalid_request
            title: One or more fields are not valid
            status: 422
            code: invalid_request
            retryable: false
    SdkVersionUnsupported:
      description: 'This SDK release is switched off: upgrade the SDK'
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/sdk_version_unsupported
            title: 'This SDK release is switched off: upgrade the SDK'
            status: 426
            code: sdk_version_unsupported
            retryable: false
    RateLimited:
      description: Too many requests
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        RateLimit-Limit:
          description: Requests allowed per minute for this credential.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
        RateLimit-Reset:
          description: Seconds until the window is full again.
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/rate_limited
            title: Too many requests
            status: 429
            code: rate_limited
            retryable: true
    InternalError:
      description: Something went wrong on our side
      headers:
        X-Request-Id:
          description: Quote this when contacting support.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.kallabot.com/errors/internal_error
            title: Something went wrong on our side
            status: 500
            code: internal_error
            retryable: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: kb_live_<lookup>_<secret> | kbp_live_<lookup>_<secret>
      description: >-
        An API key from Settings → API keys, sent as `Authorization: Bearer
        kb_live_…`. A workspace key starts `kb_`; a personal key starts `kbp_`
        and acts as its owner.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.