BrightshoalDocsOpen console
MenuAssistants

API reference

Assistants

An assistant is one agent: its instructions, model, voice, tools and channels. Every call and chat runs on an assistant, and every update creates a new version.

Create an assistant

POST/api/assistants

Creates an assistant at version 1. config needs agent.instructions and session.llm, session.stt and session.tts, each with a provider and model from the registry; everything else has a default. An org-wide key must name project_id. Validation checks the shape, not that the provider account works: place a sandbox call or chat to be sure.

Secret API key, not a viewer key. How it works

Request body

  • project_idstring

    Required for an org-wide key; ignored (must match) for a project-scoped key.

  • namestringrequirednot empty

  • configAssistantConfigrequired

    The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

    7 attributes
    • schedulingobject

      Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

      2 attributes
      • versionintegerrequired

      • event_type_idsarray of stringrequiredup to 100 items

    • agentobjectrequired

      1 attribute
      • instructionsstringrequired

    • toolsAssistantTools

      Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

      1 attribute
      • definitionsarray of AssistantToolDefinition

        7 attributes
        • namestringrequired

        • descriptionstring

        • parametersobject

          JSON Schema for the arguments, as exposed to the model.

        • enabledboolean

          False keeps the tool saved, with its request, but offers it on no channel.

          Default true

        • channelsarray of string

          Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

        • read_onlyboolean

          True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

          Default false

        • requestobjectwrite-only, never returned

          Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

          4 attributes
          • urlstringrequireduri

          • methodstring

            One of GET POST PUT PATCH DELETE

          • headersobject

          • timeout_msinteger1 to 120000

    • sessionanyrequired

      5 attributes
      • llmobject

        2 attributes
        • providerstringnot empty

        • modelstringrequirednot empty

      • realtimeobject

        2 attributes
        • providerstringrequirednot empty

        • modelstringnot empty

      • sttProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • ttsProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          7 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

          • requestobjectwrite-only, never returned

            Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

            4 attributes
            • urlstringrequireduri

            • methodstring

              One of GET POST PUT PATCH DELETE

            • headersobject

            • timeout_msinteger1 to 120000

    • variablesarray of AssistantVariableDefup to 50 items

      Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

      4 attributes
      • keystringrequiredup to 64 characters

      • labelstringup to 120 characters

      • descriptionstringup to 500 characters

      • defaultstringup to 2000 characters

    • lead_captureobject

      Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

      4 attributes
      • enabledboolean

      • promptstring

      • require_completeboolean

      • fieldsarray of object

        5 attributes
        • keystringrequired

        • labelstring

        • typestring

          One of string email phone number

        • requiredboolean

        • optionsarray of stringup to 6 items

    • knowledgeobject

      The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

      3 attributes
      • chatbooleanrequired

        Search it in web chat and WhatsApp.

      • voicebooleanrequired

        Search it on calls. Needs a pipeline session, not realtime.

      • priorityintegerrequired0 to 100

        Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

Returns

201 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants
curl -X POST "https://api.brightshoal.com/api/assistants" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "project_id": "proj_2f9c41d0a8b34e6f9d1c7a5b3e8f0a12",
  "config": {
    "agent": {
      "instructions": "You answer enquiries for Acme Travel. Be brief and friendly."
    },
    "session": {
      "llm": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "stt": {
        "provider": "deepgram",
        "model": "nova-3"
      },
      "tts": {
        "provider": "elevenlabs",
        "model": "eleven_flash_v2_5"
      }
    },
    "channels": {
      "web_chat": {
        "enabled": true,
        "allowed_origins": [
          "https://www.acmetravel.com"
        ]
      }
    }
  }
}'
Response 201
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

List assistants

GET/api/assistants

Every assistant in scope with its full current configuration. Secrets in the config come back as <key>_set flags. Archived assistants are left out unless archived=true.

Secret API key. How it works

Query parameters

  • project_idstring

    Only this project's assistants.

  • archivedboolean

    true: only archived assistants. Absent: only live ones.

Returns

200 OK

Response attributes
  • dataarray of Assistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants
curl "https://api.brightshoal.com/api/assistants" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "effective_hours": {
        "value": [
          {
            "day": "mon",
            "open": {},
            "close": {}
          }
        ],
        "source": "assistant"
      },
      "effective_timezone": {
        "value": "string",
        "source": "assistant"
      },
      "effective_team_phone": {
        "value": "string",
        "source": "assistant"
      },
      "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "config": {
        "scheduling": {
          "version": 1,
          "event_type_ids": [
            {}
          ]
        },
        "agent": {
          "instructions": "You answer enquiries for Acme Travel."
        },
        "tools": {
          "definitions": [
            {}
          ]
        },
        "session": null,
        "variables": [
          {
            "key": {},
            "label": {},
            "description": {},
            "default": {}
          }
        ],
        "lead_capture": {
          "enabled": true,
          "prompt": "You answer enquiries for Acme Travel.",
          "require_complete": true,
          "fields": [
            {}
          ]
        },
        "knowledge": {
          "key": {
            "chat": {},
            "voice": {},
            "priority": {}
          }
        }
      },
      "version": 1,
      "draft_revision": 1,
      "draft": {
        "revision": 1,
        "base_version": 1,
        "updated_at": "2026-10-28T09:30:00.000Z"
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z",
      "archived_at": "2026-10-28T09:30:00.000Z"
    }
  ]
}

Get an assistant and its effective business settings

GET/api/assistants/{id}

One assistant with its stored configuration and version, archived or not. effective_hours, effective_timezone and effective_team_phone report the runtime values and their assistant/business source, resolved from the current business site profile without copying into config.

Secret API key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants/{id}
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Update an assistant

PATCH/api/assistants/{id}

Send name, config or both. A config replaces the whole stored configuration (it is not merged), except that omitted secrets and tool request specs are kept: read the assistant, change what you need and send the full config back. Each update bumps version. An archived assistant cannot be changed (409 assistant_archived): restore it first.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Request body

  • namestringnot empty

  • configAssistantConfig

    The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

    7 attributes
    • schedulingobject

      Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

      2 attributes
      • versionintegerrequired

      • event_type_idsarray of stringrequiredup to 100 items

    • agentobjectrequired

      1 attribute
      • instructionsstringrequired

    • toolsAssistantTools

      Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

      1 attribute
      • definitionsarray of AssistantToolDefinition

        7 attributes
        • namestringrequired

        • descriptionstring

        • parametersobject

          JSON Schema for the arguments, as exposed to the model.

        • enabledboolean

          False keeps the tool saved, with its request, but offers it on no channel.

          Default true

        • channelsarray of string

          Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

        • read_onlyboolean

          True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

          Default false

        • requestobjectwrite-only, never returned

          Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

          4 attributes
          • urlstringrequireduri

          • methodstring

            One of GET POST PUT PATCH DELETE

          • headersobject

          • timeout_msinteger1 to 120000

    • sessionanyrequired

      5 attributes
      • llmobject

        2 attributes
        • providerstringnot empty

        • modelstringrequirednot empty

      • realtimeobject

        2 attributes
        • providerstringrequirednot empty

        • modelstringnot empty

      • sttProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • ttsProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          7 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

          • requestobjectwrite-only, never returned

            Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

            4 attributes
            • urlstringrequireduri

            • methodstring

              One of GET POST PUT PATCH DELETE

            • headersobject

            • timeout_msinteger1 to 120000

    • variablesarray of AssistantVariableDefup to 50 items

      Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

      4 attributes
      • keystringrequiredup to 64 characters

      • labelstringup to 120 characters

      • descriptionstringup to 500 characters

      • defaultstringup to 2000 characters

    • lead_captureobject

      Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

      4 attributes
      • enabledboolean

      • promptstring

      • require_completeboolean

      • fieldsarray of object

        5 attributes
        • keystringrequired

        • labelstring

        • typestring

          One of string email phone number

        • requiredboolean

        • optionsarray of stringup to 6 items

    • knowledgeobject

      The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

      3 attributes
      • chatbooleanrequired

        Search it in web chat and WhatsApp.

      • voicebooleanrequired

        Search it on calls. Needs a pipeline session, not realtime.

      • priorityintegerrequired0 to 100

        Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

  • expected_versionintegermin 1

    The version the caller read. A save over a newer version is refused with 409 version_conflict and the current_version.

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PATCH /api/assistants/{id}
curl -X PATCH "https://api.brightshoal.com/api/assistants/ASSISTANT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk (UK)"
}'
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Archive an assistant

POST/api/assistants/{id}/archive

Its widget, chats and calls stop at once: widget keys answer 404 for it, open chats get no more replies, WhatsApp numbers stop answering, and phone numbers reject calls; numbers and keys keep their binding. Nothing is deleted, edits are refused with 409 assistant_archived, and it leaves the assistants list. Archiving an archived assistant is a no-op. Needs the admin role; audited as assistant.archived.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/archive
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/archive" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Restore an archived assistant

POST/api/assistants/{id}/restore

Its widget keys, numbers and chats serve it again. Restoring a live assistant is a no-op. Needs the admin role; audited as assistant.unarchived.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/restore
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Delete an archived assistant permanently

DELETE/api/assistants/{id}

Only an archived assistant can be deleted: 409 not_archived otherwise. Its versions, knowledge base links, assistant-bound widget keys (preview links) and GA4 delivery status are deleted; phone and WhatsApp numbers bound to it are left without an assistant. Its past calls, conversations and leads stay readable. Cannot be undone.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

200 OK

Response attributes
  • dataDeleteResultrequired

    2 attributes
    • idstringrequired

    • deletedbooleanrequired

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 not_archived: archive the assistant first.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
DELETE /api/assistants/{id}
curl -X DELETE "https://api.brightshoal.com/api/assistants/ASSISTANT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "deleted": true
  }
}

Upload an assistant avatar

POST/api/assistant-avatars

Stores a PNG, JPEG or WebP (at most 512 KB and 4096 pixels a side) as a public org asset and returns its URL, for channels.web_chat.appearance.avatar_url. The same picture always gets the same URL.

Secret API key, not a viewer key. How it works

Request body

  • content_typestringrequired

    One of image/png image/jpeg image/webp

  • base64stringrequired

    The file's bytes, base64-encoded.

Returns

201 OK

Response attributes
  • dataAssistantAvatarrequired

    1 attribute
    • urlstringrequireduri

  • 400 invalid_request for a malformed body, or avatar_empty, avatar_too_large, avatar_type_mismatch (the bytes are not the declared image type) or avatar_dimensions, in error.
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 asset_storage_not_configured: this deployment has no storage for uploaded images.
POST /api/assistant-avatars
curl -X POST "https://api.brightshoal.com/api/assistant-avatars" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "image/png",
  "base64": "string"
}'
Response 201
{
  "data": {
    "url": "https://example.com/hook"
  }
}

Start a sandbox chat conversation

POST/api/assistants/{id}/chat-test-conversation

Starts a one-hour conversation with an assistant, including when public web chat is off, without a publishable key or an origin check, for trying a prompt from your own tooling. Use the returned token with the public chat routes. Sandbox conversations (mode test) carry metadata.test and are left out of lists and analytics unless asked for.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

201 Sandbox conversation created

Response attributes
  • dataobjectrequired

    2 attributes
    • conversation_idstringrequired

    • tokenstringrequired

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 assistant_archived: the assistant is archived; restore it first
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/chat-test-conversation
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/chat-test-conversation" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 201
{
  "data": {
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "token": "string"
  }
}

Get the assistant's draft

GET/api/assistants/{id}/draft

The config being worked on in sandbox mode, or null when there is none. Sandbox chats (sandbox keys and the console's sandbox chat) run it; visitors never do until it is published.

Secret API key. How it works

Path parameters

  • idstringrequired

Returns

200 OK

Response attributes
  • dataAssistantDraft | nullrequired

    11 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • assistant_idstring

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • hidden_changesarray of string

      Paths that differ from live but read back the same: credentials and tool request specs. Values are never returned.

    • revisioninteger

    • base_versioninteger

      The live version the draft started from.

    • live_versioninteger

    • staleboolean

      Live was edited after the draft started; publishing is refused.

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants/{id}/draft
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "hidden_changes": [
      "string"
    ],
    "revision": 1,
    "base_version": 1,
    "live_version": 1,
    "stale": true,
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Save the assistant's draft

PUT/api/assistants/{id}/draft

Starts a draft from the live config, or replaces the current one. Credentials and tool request specs left out are kept from the stored draft (or from live for a new draft). 409 assistant_archived for an archived assistant.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

Request body

  • configAssistantConfigrequired

    The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

    7 attributes
    • schedulingobject

      Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

      2 attributes
      • versionintegerrequired

      • event_type_idsarray of stringrequiredup to 100 items

    • agentobjectrequired

      1 attribute
      • instructionsstringrequired

    • toolsAssistantTools

      Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

      1 attribute
      • definitionsarray of AssistantToolDefinition

        7 attributes
        • namestringrequired

        • descriptionstring

        • parametersobject

          JSON Schema for the arguments, as exposed to the model.

        • enabledboolean

          False keeps the tool saved, with its request, but offers it on no channel.

          Default true

        • channelsarray of string

          Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

        • read_onlyboolean

          True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

          Default false

        • requestobjectwrite-only, never returned

          Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

          4 attributes
          • urlstringrequireduri

          • methodstring

            One of GET POST PUT PATCH DELETE

          • headersobject

          • timeout_msinteger1 to 120000

    • sessionanyrequired

      5 attributes
      • llmobject

        2 attributes
        • providerstringnot empty

        • modelstringrequirednot empty

      • realtimeobject

        2 attributes
        • providerstringrequirednot empty

        • modelstringnot empty

      • sttProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • ttsProviderModel

        2 attributes
        • providerstringrequirednot empty

        • modelstringrequirednot empty

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          7 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

          • requestobjectwrite-only, never returned

            Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.

            4 attributes
            • urlstringrequireduri

            • methodstring

              One of GET POST PUT PATCH DELETE

            • headersobject

            • timeout_msinteger1 to 120000

    • variablesarray of AssistantVariableDefup to 50 items

      Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

      4 attributes
      • keystringrequiredup to 64 characters

      • labelstringup to 120 characters

      • descriptionstringup to 500 characters

      • defaultstringup to 2000 characters

    • lead_captureobject

      Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

      4 attributes
      • enabledboolean

      • promptstring

      • require_completeboolean

      • fieldsarray of object

        5 attributes
        • keystringrequired

        • labelstring

        • typestring

          One of string email phone number

        • requiredboolean

        • optionsarray of stringup to 6 items

    • knowledgeobject

      The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

      3 attributes
      • chatbooleanrequired

        Search it in web chat and WhatsApp.

      • voicebooleanrequired

        Search it on calls. Needs a pipeline session, not realtime.

      • priorityintegerrequired0 to 100

        Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

  • expected_draft_revisionintegermin 0

    The draft_revision the caller read. A save over a newer draft is refused with 409 draft_conflict.

  • expected_versionintegermin 1

    The live version the caller edited from. A save that starts a new draft is refused with 409 live_changed when live has moved on since.

Returns

200 OK

Response attributes
  • dataAssistantDraft | nullrequired

    11 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • assistant_idstring

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • hidden_changesarray of string

      Paths that differ from live but read back the same: credentials and tool request specs. Values are never returned.

    • revisioninteger

    • base_versioninteger

      The live version the draft started from.

    • live_versioninteger

    • staleboolean

      Live was edited after the draft started; publishing is refused.

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/assistants/{id}/draft
curl -X PUT "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "agent": {
      "instructions": "You answer enquiries for Acme Travel."
    },
    "session": null
  }
}'
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "hidden_changes": [
      "string"
    ],
    "revision": 1,
    "base_version": 1,
    "live_version": 1,
    "stale": true,
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Discard the assistant's draft

DELETE/api/assistants/{id}/draft

Throws the draft away and returns the assistant; the live config is unchanged. Succeeds when there is no draft too.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

Query parameters

  • expected_draft_revisioninteger

    The draft_revision the caller looked at; a newer draft is not discarded (409 draft_conflict).

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
DELETE /api/assistants/{id}/draft
curl -X DELETE "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Update the draft from live

POST/api/assistants/{id}/draft/rebase

After live changed under a draft (a stale draft), lays what the draft changed since its base version over today's live config, so it can be published without undoing live's change. Settings both changed differently are refused with 409 rebase_conflict and their paths, unless keep_draft keeps the draft's values; those paths are returned as kept_draft. Also 409 no_draft, draft_conflict, rebase_unavailable when the base version is not in history, or rebase_invalid (with issues) when the merged config would not be valid; the draft is then left as it was. 409 assistant_archived for an archived assistant.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

Request body

  • expected_draft_revisionintegermin 0

  • keep_draftboolean

    Keep the draft's value where live changed the same setting differently.

Returns

200 The updated draft, and the settings where the draft's value was kept over live's.

Response attributes
  • dataAssistantDraft | nullrequired

    11 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • assistant_idstring

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • hidden_changesarray of string

      Paths that differ from live but read back the same: credentials and tool request specs. Values are never returned.

    • revisioninteger

    • base_versioninteger

      The live version the draft started from.

    • live_versioninteger

    • staleboolean

      Live was edited after the draft started; publishing is refused.

    • updated_atstringISO 8601 timestamp

  • kept_draftarray of stringrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/draft/rebase
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft/rebase" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_draft_revision": 1,
  "keep_draft": true
}'
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "hidden_changes": [
      "string"
    ],
    "revision": 1,
    "base_version": 1,
    "live_version": 1,
    "stale": true,
    "updated_at": "2026-10-28T09:30:00.000Z"
  },
  "kept_draft": [
    "string"
  ]
}

Read the assistant's Google Analytics settings

GET/api/assistants/{id}/integrations/google-analytics

The GA4 settings live chats send with: the assistant-wide property, web chat's own override and its browser options, which property is in effect, and the latest server-side delivery. API secrets are write-only and come back as api_secret_set, true when the organization's google_analytics connection for that measurement ID holds one. effective follows the server's rule: web chat's property when it has both a measurement ID and a secret, else the assistant's when that has both, else none. status.last_status delivered means Google accepted the request, which its Measurement Protocol does for almost any payload; use the test endpoint to check one.

Secret API key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Returns

200 OK

Response attributes
  • dataGa4Settingsrequired

    4 attributes
    • assistantobjectrequired

      The assistant-wide property (integrations.google_analytics), shared by every channel.

      2 attributes
      • measurement_idstring | nullrequired

      • api_secret_setbooleanrequired

    • web_chatobjectrequired

      Web chat's own property (channels.web_chat.analytics.ga4) and its options, defaults filled in.

      7 attributes
      • measurement_idstring | nullrequired

      • api_secret_setbooleanrequired

      • data_layerbooleanrequired

        Push the funnel to the host page's dataLayer.

      • gtagbooleanrequired

        Call the host page's gtag().

      • event_prefixstringrequired

        Prepended to every event name. Default chat_.

      • require_consentbooleanrequired

      • page_pathsstringrequired

        One of section full

    • effectiveobjectrequired

      The property server-side events go to now.

      2 attributes
      • sourcestring | nullrequired

        One of web_chat assistant

      • measurement_idstring | nullrequired

    • statusobject | nullrequired

      The latest server-side hit; null before the first.

      5 attributes
      • last_eventstringrequired

      • last_statusstringrequired

        One of delivered rejected unreachable not_configured no_identity

      • last_success_atstring | nullrequiredISO 8601 timestamp

      • last_failure_atstring | nullrequiredISO 8601 timestamp

      • last_failure_reasonstring | nullrequired

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants/{id}/integrations/google-analytics
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/integrations/google-analytics" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "assistant": {
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "api_secret_set": true
    },
    "web_chat": {
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "api_secret_set": true,
      "data_layer": true,
      "gtag": true,
      "event_prefix": "string",
      "require_consent": true,
      "page_paths": "section"
    },
    "effective": {
      "source": "web_chat",
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
    },
    "status": {
      "last_event": "string",
      "last_status": "delivered",
      "last_success_at": "2026-10-28T09:30:00.000Z",
      "last_failure_at": "2026-10-28T09:30:00.000Z",
      "last_failure_reason": "string"
    }
  }
}

Change the assistant's Google Analytics settings

PUT/api/assistants/{id}/integrations/google-analytics

Requires an admin. Every field is optional; only what you send changes. assistant: null removes the assistant-wide property and web_chat.measurement_id: null removes web chat's own, so web chat falls back to the assistant's. An api_secret is stored as the organization's google_analytics connection for that measurement ID (shared by every assistant naming the ID; the config keeps only the ID). It is required when no secret is stored for the ID and none was stored in that place; otherwise leaving it out keeps the stored one. The change lands on the live config and on the draft when there is one, takes effect at once, and keeps a current draft current (its revision is bumped, so reload a draft you hold before saving it). Recorded as an assistant version and audited. Answers with the settings as read.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Request body

  • assistantobject | null

    2 attributes
    • measurement_idstringrequired

    • api_secretstringup to 128 characterswrite-only, never returned

  • web_chatobject

    7 attributes
    • measurement_idstring | null

    • api_secretstringup to 128 characterswrite-only, never returned

    • data_layerboolean

    • gtagboolean

    • event_prefixstring

      Not ga_, google_ or firebase_, which GA4 reserves.

    • require_consentboolean

    • page_pathsstring

      One of section full

Returns

200 OK

Response attributes
  • dataGa4Settingsrequired

    4 attributes
    • assistantobjectrequired

      The assistant-wide property (integrations.google_analytics), shared by every channel.

      2 attributes
      • measurement_idstring | nullrequired

      • api_secret_setbooleanrequired

    • web_chatobjectrequired

      Web chat's own property (channels.web_chat.analytics.ga4) and its options, defaults filled in.

      7 attributes
      • measurement_idstring | nullrequired

      • api_secret_setbooleanrequired

      • data_layerbooleanrequired

        Push the funnel to the host page's dataLayer.

      • gtagbooleanrequired

        Call the host page's gtag().

      • event_prefixstringrequired

        Prepended to every event name. Default chat_.

      • require_consentbooleanrequired

      • page_pathsstringrequired

        One of section full

    • effectiveobjectrequired

      The property server-side events go to now.

      2 attributes
      • sourcestring | nullrequired

        One of web_chat assistant

      • measurement_idstring | nullrequired

    • statusobject | nullrequired

      The latest server-side hit; null before the first.

      5 attributes
      • last_eventstringrequired

      • last_statusstringrequired

        One of delivered rejected unreachable not_configured no_identity

      • last_success_atstring | nullrequiredISO 8601 timestamp

      • last_failure_atstring | nullrequiredISO 8601 timestamp

      • last_failure_reasonstring | nullrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 assistant_archived: the assistant is archived; restore it first
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/assistants/{id}/integrations/google-analytics
curl -X PUT "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/integrations/google-analytics" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "assistant": {
    "measurement_id": "G-ABC123XYZ9"
  },
  "web_chat": {
    "measurement_id": "G-ABC123XYZ9",
    "api_secret": "whsec_..."
  }
}'
Response 200
{
  "data": {
    "assistant": {
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "api_secret_set": true
    },
    "web_chat": {
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "api_secret_set": true,
      "data_layer": true,
      "gtag": true,
      "event_prefix": "string",
      "require_consent": true,
      "page_paths": "section"
    },
    "effective": {
      "source": "web_chat",
      "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
    },
    "status": {
      "last_event": "string",
      "last_status": "delivered",
      "last_success_at": "2026-10-28T09:30:00.000Z",
      "last_failure_at": "2026-10-28T09:30:00.000Z",
      "last_failure_reason": "string"
    }
  }
}

Send a Google Analytics test event

POST/api/assistants/{id}/integrations/google-analytics/test

Requires an admin. Checks a test_event (with the assistant's event prefix) against GA4's validation endpoint, then, if it passes, sends it for real with debug_mode so it shows in the property's DebugView. Tests the values you send, both or neither; without them, the property live chats send with. GA4's validator checks the payload, not that the secret belongs to the property, so watch DebugView to confirm. Not counted as the assistant's delivery status. At most 10 a minute per assistant.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Assistant id, asst_....

Request body

  • measurement_idstring

  • api_secretstringup to 128 characterswrite-only, never returned

Returns

200 The test's outcome

Response attributes
  • dataobjectrequired

    6 attributes
    • validbooleanrequired

      GA4's validator found nothing wrong.

    • messagesarray of stringrequired

      What the validator objected to.

    • sentbooleanrequired

      The real event was accepted.

    • reasonstring

      Why it was not valid or not sent.

      One of not_configured no_identity rejected unreachable

    • event_namestringrequired

    • measurement_idstring | nullrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 rate_limited: more than 10 test events this minute. Carries Retry-After.
POST /api/assistants/{id}/integrations/google-analytics/test
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/integrations/google-analytics/test" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "measurement_id": "G-ABC123XYZ9",
  "api_secret": "whsec_..."
}'
Response 200
{
  "data": {
    "valid": true,
    "messages": [
      "Hi, can I book a trip to Lisbon in May?"
    ],
    "sent": true,
    "reason": "not_configured",
    "event_name": "string",
    "measurement_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Publish the draft

POST/api/assistants/{id}/publish

Makes the draft the live config and records the new version. Refused with 409 no_draft, version_conflict, draft_conflict, live_changed when live was edited after the draft started, or assistant_archived.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

Request body

  • expected_versionintegermin 1

  • expected_draft_revisionintegermin 0

  • notestringup to 500 characters

Returns

200 OK

Response attributes
  • dataAssistantrequired

    14 attributes
    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/publish
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/publish" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_version": 1,
  "expected_draft_revision": 1
}'
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": "string",
          "close": "string"
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

List the assistant's config history

GET/api/assistants/{id}/versions

Every live config the assistant has had, newest first (the latest 100).

Secret API key. How it works

Path parameters

  • idstringrequired

Returns

200 OK

Response attributes
  • dataarray of AssistantVersionrequired

    8 attributes
    • assistant_idstringrequired

    • versionintegerrequired

    • namestring

    • sourcestringrequired

      One of create api_edit publish restore bulk_update seed

    • created_bystring | null

    • notestring | null

    • created_atstringISO 8601 timestamp

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants/{id}/versions
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/versions" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "version": 1,
      "name": "Front desk",
      "source": "create",
      "created_by": "string",
      "note": "string",
      "created_at": "2026-10-28T09:30:00.000Z",
      "config": {
        "scheduling": {
          "version": 1,
          "event_type_ids": [
            {}
          ]
        },
        "agent": {
          "instructions": "You answer enquiries for Acme Travel."
        },
        "tools": {
          "definitions": [
            {}
          ]
        },
        "session": null,
        "variables": [
          {
            "key": {},
            "label": {},
            "description": {},
            "default": {}
          }
        ],
        "lead_capture": {
          "enabled": true,
          "prompt": "You answer enquiries for Acme Travel.",
          "require_complete": true,
          "fields": [
            {}
          ]
        },
        "knowledge": {
          "key": {
            "chat": {},
            "voice": {},
            "priority": {}
          }
        }
      }
    }
  ]
}

Get one version of the assistant's config

GET/api/assistants/{id}/versions/{version}

The live config the assistant had at that version, as the history list returns it. 404 for a version not in its history.

Secret API key. How it works

Path parameters

  • idstringrequired

  • versionintegerrequired

Returns

200 OK

Response attributes
  • dataAssistantVersionrequired

    8 attributes
    • assistant_idstringrequired

    • versionintegerrequired

    • namestring

    • sourcestringrequired

      One of create api_edit publish restore bulk_update seed

    • created_bystring | null

    • notestring | null

    • created_atstringISO 8601 timestamp

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/assistants/{id}/versions/{version}
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/versions/VERSION" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "name": "Front desk",
    "source": "create",
    "created_by": "string",
    "note": "string",
    "created_at": "2026-10-28T09:30:00.000Z",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {
            "name": {},
            "description": {},
            "parameters": {},
            "enabled": {},
            "channels": {},
            "read_only": {}
          }
        ]
      },
      "session": null,
      "variables": [
        {
          "key": "string",
          "label": "string",
          "description": "string",
          "default": "string"
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {
            "key": {},
            "label": {},
            "type": "string",
            "required": {},
            "options": {}
          }
        ]
      },
      "knowledge": {
        "key": {
          "chat": true,
          "voice": true,
          "priority": 1
        }
      }
    }
  }
}

Restore a version

POST/api/assistants/{id}/versions/{version}/restore

Brings an old config back with today's credentials and tool auth: into the draft by default, or straight to live with target live. 409 assistant_archived for an archived assistant.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

  • versionintegerrequired

Request body

  • targetstring

    One of draft live

    Default "draft"

  • expected_versionintegermin 1

  • expected_draft_revisionintegermin 0

Returns

200 The draft it was restored into, or the assistant with target live.

Response attributes
  • dataAssistantDraft | null | Assistantrequired

    One of 2 shapes

    AssistantDraft

    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • assistant_idstring

    • configAssistantConfig

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • hidden_changesarray of string

      Paths that differ from live but read back the same: credentials and tool request specs. Values are never returned.

    • revisioninteger

    • base_versioninteger

      The live version the draft started from.

    • live_versioninteger

    • staleboolean

      Live was edited after the draft started; publishing is refused.

    • updated_atstringISO 8601 timestamp

    Assistant

    • effective_hoursobjectrequired

      Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

      2 attributes
      • valuearray of object | nullrequired

        3 attributes
        • daystringrequired

          One of mon tue wed thu fri sat sun

        • openstringrequired

        • closestringrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_timezoneobjectrequired

      Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • effective_team_phoneobjectrequired

      Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

      2 attributes
      • valuestring | nullrequired

      • sourcestring | nullrequired

        One of assistant business

    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • configAssistantConfigrequired

      The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

      7 attributes
      • schedulingobject

        Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

        2 attributes
        • versionintegerrequired

        • event_type_idsarray of stringrequiredup to 100 items

      • agentobjectrequired

        1 attribute
        • instructionsstringrequired

      • toolsAssistantTools

        Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

        1 attribute
        • definitionsarray of AssistantToolDefinition

          6 attributes
          • namestringrequired

          • descriptionstring

          • parametersobject

            JSON Schema for the arguments, as exposed to the model.

          • enabledboolean

            False keeps the tool saved, with its request, but offers it on no channel.

            Default true

          • channelsarray of string

            Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

          • read_onlyboolean

            True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

            Default false

      • sessionanyrequired

        5 attributes
        • llmobject

          2 attributes
          • providerstringnot empty

          • modelstringrequirednot empty

        • realtimeobject

          2 attributes
          • providerstringrequirednot empty

          • modelstringnot empty

        • sttProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • ttsProviderModel

          2 attributes
          • providerstringrequirednot empty

          • modelstringrequirednot empty

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

      • variablesarray of AssistantVariableDefup to 50 items

        Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

        4 attributes
        • keystringrequiredup to 64 characters

        • labelstringup to 120 characters

        • descriptionstringup to 500 characters

        • defaultstringup to 2000 characters

      • lead_captureobject

        Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

        4 attributes
        • enabledboolean

        • promptstring

        • require_completeboolean

        • fieldsarray of object

          5 attributes
          • keystringrequired

          • labelstring

          • typestring

            One of string email phone number

          • requiredboolean

          • optionsarray of stringup to 6 items

      • knowledgeobject

        The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

        3 attributes
        • chatbooleanrequired

          Search it in web chat and WhatsApp.

        • voicebooleanrequired

          Search it on calls. Needs a pipeline session, not realtime.

        • priorityintegerrequired0 to 100

          Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

    • versionintegerrequired

    • draft_revisioninteger

      The revision a draft save names as expected_draft_revision; 0 before the first draft.

    • draftobject | null

      Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

      3 attributes
      • revisioninteger

      • base_versioninteger

      • updated_atstringISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. Archived, no widget, chat or call serves it.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/assistants/{id}/versions/{version}/restore
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/versions/VERSION/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "draft",
  "expected_version": 1
}'
Response 200
{
  "data": {
    "effective_hours": {
      "value": [
        {
          "day": "mon",
          "open": {},
          "close": {}
        }
      ],
      "source": "assistant"
    },
    "effective_timezone": {
      "value": "string",
      "source": "assistant"
    },
    "effective_team_phone": {
      "value": "string",
      "source": "assistant"
    },
    "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "config": {
      "scheduling": {
        "version": 1,
        "event_type_ids": [
          {}
        ]
      },
      "agent": {
        "instructions": "You answer enquiries for Acme Travel."
      },
      "tools": {
        "definitions": [
          {}
        ]
      },
      "session": null,
      "variables": [
        {
          "key": {},
          "label": {},
          "description": {},
          "default": {}
        }
      ],
      "lead_capture": {
        "enabled": true,
        "prompt": "You answer enquiries for Acme Travel.",
        "require_complete": true,
        "fields": [
          {}
        ]
      },
      "knowledge": {
        "key": {
          "chat": {},
          "voice": {},
          "priority": {}
        }
      }
    },
    "version": 1,
    "draft_revision": 1,
    "draft": {
      "revision": 1,
      "base_version": 1,
      "updated_at": "2026-10-28T09:30:00.000Z"
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "archived_at": "2026-10-28T09:30:00.000Z"
  }
}

Draft an assistant from a website

POST/api/assistants/draft-from-website

Admin only. Resolves the caller's project, reuses or collects site facts (up to 30 seconds), and uses the project's own model connection (up to 45 seconds). Missing credentials or invalid model output uses a deterministic template. Creates version 1 and an audit entry through normal assistant validation. Public web chat stays off. Organization knowledge access is required to import and attach website pages.

Secret API key, not a viewer key. How it works

Request body

  • project_idstringnot empty

  • websitestringup to 2048 characters

  • goalstringrequired

    One of leads booking answers

  • descriptionstringup to 2000 characters

Returns

201 OK

Response attributes
  • dataWebsiteAssistantDraftrequired

    2 attributes
    • assistantAssistantrequired

      14 attributes
      • effective_hoursobjectrequired

        Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.

        2 attributes
        • valuearray of object | nullrequired

          3 attributes
          • daystringrequired

            One of mon tue wed thu fri sat sun

          • openstringrequired

          • closestringrequired

        • sourcestring | nullrequired

          One of assistant business

      • effective_timezoneobjectrequired

        Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.

        2 attributes
        • valuestring | nullrequired

        • sourcestring | nullrequired

          One of assistant business

      • effective_team_phoneobjectrequired

        Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.

        2 attributes
        • valuestring | nullrequired

        • sourcestring | nullrequired

          One of assistant business

      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • namestringrequired

      • configAssistantConfigrequired

        The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as <key>_set: boolean, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back api_secret_set: true when its secret is stored, and a write that sends api_secret in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.

        7 attributes
        • schedulingobject

          Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy.

          2 attributes
          • versionintegerrequired

          • event_type_idsarray of stringrequiredup to 100 items

        • agentobjectrequired

          1 attribute
          • instructionsstringrequired

        • toolsAssistantTools

          Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

          1 attribute
          • definitionsarray of AssistantToolDefinition

            6 attributes
            • namestringrequired

            • descriptionstring

            • parametersobject

              JSON Schema for the arguments, as exposed to the model.

            • enabledboolean

              False keeps the tool saved, with its request, but offers it on no channel.

              Default true

            • channelsarray of string

              Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

            • read_onlyboolean

              True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

              Default false

        • sessionanyrequired

          5 attributes
          • llmobject

            2 attributes
            • providerstringnot empty

            • modelstringrequirednot empty

          • realtimeobject

            2 attributes
            • providerstringrequirednot empty

            • modelstringnot empty

          • sttProviderModel

            2 attributes
            • providerstringrequirednot empty

            • modelstringrequirednot empty

          • ttsProviderModel

            2 attributes
            • providerstringrequirednot empty

            • modelstringrequirednot empty

          • toolsAssistantTools

            Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.

            1 attribute
            • definitionsarray of AssistantToolDefinition

              6 attributes
              • namestringrequired

              • descriptionstring

              • parametersobject

                JSON Schema for the arguments, as exposed to the model.

              • enabledboolean

                False keeps the tool saved, with its request, but offers it on no channel.

                Default true

              • channelsarray of string

                Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.

              • read_onlyboolean

                True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat.

                Default false

        • variablesarray of AssistantVariableDefup to 50 items

          Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime.

          4 attributes
          • keystringrequiredup to 64 characters

          • labelstringup to 120 characters

          • descriptionstringup to 500 characters

          • defaultstringup to 2000 characters

        • lead_captureobject

          Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type string, email or phone, required, options). When set it replaces channels.web_chat.lead_capture as a whole object, with no field merge; that older key is still read when this one is absent.

          4 attributes
          • enabledboolean

          • promptstring

          • require_completeboolean

          • fieldsarray of object

            5 attributes
            • keystringrequired

            • labelstring

            • typestring

              One of string email phone number

            • requiredboolean

            • optionsarray of stringup to 6 items

        • knowledgeobject

          The knowledge bases the assistant answers from, by knowledge base id (kb_...). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send {} to detach every base. An entry with both chat and voice false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 organization_knowledge_access_required for a project key or knowledge_forbidden without editor access, 400 knowledge_base_not_found for an unknown id, 409 knowledge_voice_requires_pipeline_assistant for voice on a realtime session. Each refusal names the base in knowledge_base_id.

          3 attributes
          • chatbooleanrequired

            Search it in web chat and WhatsApp.

          • voicebooleanrequired

            Search it on calls. Needs a pipeline session, not realtime.

          • priorityintegerrequired0 to 100

            Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel.

      • versionintegerrequired

      • draft_revisioninteger

        The revision a draft save names as expected_draft_revision; 0 before the first draft.

      • draftobject | null

        Whether a draft exists, without its config (GET /assistants/{id}/draft has it).

        3 attributes
        • revisioninteger

        • base_versioninteger

        • updated_atstringISO 8601 timestamp

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

      • archived_atstring | nullISO 8601 timestamp

        When it was archived; null while live. Archived, no widget, chat or call serves it.

    • draftobjectrequired

      7 attributes
      • generated_bystringrequired

        One of model template

      • websitestring | nullrequired

      • knowledge_base_idstring | nullrequired

      • pagesarray of objectrequired

        3 attributes
        • urlstringrequired

        • titlestring | nullrequired

        • used_forarray of stringrequired

      • section_factsarray of object

        4 attributes
        • sectionstringrequired

        • fieldstringrequired

        • valueanyrequired

        • sourcesarray of objectrequired

          2 attributes
          • urlstringrequired

          • snippetstringrequired

      • factsobjectrequired

        7 attributes
        • business_namestring | nullrequired

        • servicesarray of stringrequired

        • hoursstring | nullrequired

        • phonestring | nullrequired

        • coloursarray of stringrequired

        • logostring | nullrequired

        • time_zonestring | nullrequired

      • missingarray of stringrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 project_not_in_scope
  • 422 website_required, or site_unreadable with reason timeout, unreachable or blocked
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 502 assistant_draft_failed: a storage or internal operation failed
POST /api/assistants/draft-from-website
curl -X POST "https://api.brightshoal.com/api/assistants/draft-from-website" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "leads"
}'
Response 201
{
  "data": {
    "assistant": {
      "effective_hours": {
        "value": [
          {
            "day": "mon",
            "open": {},
            "close": {}
          }
        ],
        "source": "assistant"
      },
      "effective_timezone": {
        "value": "string",
        "source": "assistant"
      },
      "effective_team_phone": {
        "value": "string",
        "source": "assistant"
      },
      "id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "config": {
        "scheduling": {
          "version": 1,
          "event_type_ids": [
            {}
          ]
        },
        "agent": {
          "instructions": "You answer enquiries for Acme Travel."
        },
        "tools": {
          "definitions": [
            {}
          ]
        },
        "session": null,
        "variables": [
          {
            "key": {},
            "label": {},
            "description": {},
            "default": {}
          }
        ],
        "lead_capture": {
          "enabled": true,
          "prompt": "You answer enquiries for Acme Travel.",
          "require_complete": true,
          "fields": [
            {}
          ]
        },
        "knowledge": {
          "key": {
            "chat": {},
            "voice": {},
            "priority": {}
          }
        }
      },
      "version": 1,
      "draft_revision": 1,
      "draft": {
        "revision": 1,
        "base_version": 1,
        "updated_at": "2026-10-28T09:30:00.000Z"
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z",
      "archived_at": "2026-10-28T09:30:00.000Z"
    },
    "draft": {
      "generated_by": "model",
      "website": "string",
      "knowledge_base_id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "pages": [
        {
          "url": "https://example.com/hook",
          "title": "Front desk",
          "used_for": [
            {}
          ]
        }
      ],
      "section_facts": [
        {
          "section": "string",
          "field": "string",
          "value": null,
          "sources": [
            {}
          ]
        }
      ],
      "facts": {
        "business_name": "string",
        "services": [
          "string"
        ],
        "hours": "string",
        "phone": "+14155550123",
        "colours": [
          "string"
        ],
        "logo": "string",
        "time_zone": "string"
      },
      "missing": [
        "hours"
      ]
    }
  }
}