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.
- POST
/api/assistantsCreate an assistant - GET
/api/assistantsList assistants - GET
/api/assistants/{id}Get an assistant and its effective business settings - PATCH
/api/assistants/{id}Update an assistant - POST
/api/assistants/{id}/archiveArchive an assistant - POST
/api/assistants/{id}/restoreRestore an archived assistant - DELETE
/api/assistants/{id}Delete an archived assistant permanently - POST
/api/assistant-avatarsUpload an assistant avatar - POST
/api/assistants/{id}/chat-test-conversationStart a sandbox chat conversation - GET
/api/assistants/{id}/draftGet the assistant's draft - PUT
/api/assistants/{id}/draftSave the assistant's draft - DELETE
/api/assistants/{id}/draftDiscard the assistant's draft - POST
/api/assistants/{id}/draft/rebaseUpdate the draft from live - GET
/api/assistants/{id}/integrations/google-analyticsRead the assistant's Google Analytics settings - PUT
/api/assistants/{id}/integrations/google-analyticsChange the assistant's Google Analytics settings - POST
/api/assistants/{id}/integrations/google-analytics/testSend a Google Analytics test event - POST
/api/assistants/{id}/publishPublish the draft - GET
/api/assistants/{id}/versionsList the assistant's config history - GET
/api/assistants/{id}/versions/{version}Get one version of the assistant's config - POST
/api/assistants/{id}/versions/{version}/restoreRestore a version - POST
/api/assistants/draft-from-websiteDraft an assistant from a website
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_idstringRequired for an org-wide key; ignored (must match) for a project-scoped key.
namestringrequirednot emptyconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
variablesarray of AssistantVariableDefup to 50 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. Archived, no widget, chat or call serves it.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
]
}
}
}
}'{
"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_idstringOnly this project's assistants.
archivedbooleantrue: only archived assistants. Absent: only live ones.
Returns
200 OK
Response attributes
dataarray of Assistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredAssistant id,
asst_....
Returns
200 OK
Response attributes
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredAssistant id,
asst_....
Request body
namestringnot emptyconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
variablesarray of AssistantVariableDefup to 50 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 1The 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
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. Archived, no widget, chat or call serves it.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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)"
}'{
"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
idstringrequiredAssistant id,
asst_....
Returns
200 OK
Response attributes
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen 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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/archive" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredAssistant id,
asst_....
Returns
200 OK
Response attributes
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen 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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/restore" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredAssistant id,
asst_....
Returns
200 OK
Response attributes
dataDeleteResultrequired2 attributes
idstringrequireddeletedbooleanrequired
- 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). WaitRetry-Afterseconds. 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).
curl -X DELETE "https://api.brightshoal.com/api/assistants/ASSISTANT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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_typestringrequiredOne of
image/pngimage/jpegimage/webpbase64stringrequiredThe file's bytes, base64-encoded.
Returns
201 OK
Response attributes
dataAssistantAvatarrequired1 attribute
urlstringrequireduri
- 400
invalid_requestfor a malformed body, oravatar_empty,avatar_too_large,avatar_type_mismatch(the bytes are not the declared image type) oravatar_dimensions, inerror. - 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). WaitRetry-Afterseconds. 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.
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"
}'{
"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
idstringrequiredAssistant id,
asst_....
Returns
201 Sandbox conversation created
Response attributes
dataobjectrequired2 attributes
conversation_idstringrequiredtokenstringrequired
- 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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/chat-test-conversation" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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 | nullrequired11 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
assistant_idstringconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 stringPaths that differ from live but read back the same: credentials and tool request specs. Values are never returned.
revisionintegerbase_versionintegerThe live version the draft started from.
live_versionintegerstalebooleanLive 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
configAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition7 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
falserequestobjectwrite-only, never returnedServer-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
urlstringrequiredurimethodstringOne of
GETPOSTPUTPATCHDELETEheadersobjecttimeout_msinteger1 to 120000
variablesarray of AssistantVariableDefup to 50 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 0The draft_revision the caller read. A save over a newer draft is refused with 409 draft_conflict.
expected_versionintegermin 1The 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 | nullrequired11 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
assistant_idstringconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 stringPaths that differ from live but read back the same: credentials and tool request specs. Values are never returned.
revisionintegerbase_versionintegerThe live version the draft started from.
live_versionintegerstalebooleanLive was edited after the draft started; publishing is refused.
updated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}
}'{
"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_revisionintegerThe draft_revision the caller looked at; a newer draft is not discarded (409 draft_conflict).
Returns
200 OK
Response attributes
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen 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). WaitRetry-Afterseconds. 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).
curl -X DELETE "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/draft" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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 0keep_draftbooleanKeep 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 | nullrequired11 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
assistant_idstringconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 stringPaths that differ from live but read back the same: credentials and tool request specs. Values are never returned.
revisionintegerbase_versionintegerThe live version the draft started from.
live_versionintegerstalebooleanLive 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}'{
"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
idstringrequiredAssistant id,
asst_....
Returns
200 OK
Response attributes
dataGa4Settingsrequired4 attributes
assistantobjectrequiredThe assistant-wide property (
integrations.google_analytics), shared by every channel.2 attributes
measurement_idstring | nullrequiredapi_secret_setbooleanrequired
web_chatobjectrequiredWeb chat's own property (
channels.web_chat.analytics.ga4) and its options, defaults filled in.7 attributes
measurement_idstring | nullrequiredapi_secret_setbooleanrequireddata_layerbooleanrequiredPush the funnel to the host page's dataLayer.
gtagbooleanrequiredCall the host page's gtag().
event_prefixstringrequiredPrepended to every event name. Default
chat_.require_consentbooleanrequiredpage_pathsstringrequiredOne of
sectionfull
effectiveobjectrequiredThe property server-side events go to now.
2 attributes
sourcestring | nullrequiredOne of
web_chatassistantmeasurement_idstring | nullrequired
statusobject | nullrequiredThe latest server-side hit; null before the first.
5 attributes
last_eventstringrequiredlast_statusstringrequiredOne of
deliveredrejectedunreachablenot_configuredno_identitylast_success_atstring | nullrequiredISO 8601 timestamplast_failure_atstring | nullrequiredISO 8601 timestamplast_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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/integrations/google-analytics" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredAssistant id,
asst_....
Request body
assistantobject | null2 attributes
measurement_idstringrequiredapi_secretstringup to 128 characterswrite-only, never returned
web_chatobject7 attributes
measurement_idstring | nullapi_secretstringup to 128 characterswrite-only, never returneddata_layerbooleangtagbooleanevent_prefixstringNot
ga_,google_orfirebase_, which GA4 reserves.require_consentbooleanpage_pathsstringOne of
sectionfull
Returns
200 OK
Response attributes
dataGa4Settingsrequired4 attributes
assistantobjectrequiredThe assistant-wide property (
integrations.google_analytics), shared by every channel.2 attributes
measurement_idstring | nullrequiredapi_secret_setbooleanrequired
web_chatobjectrequiredWeb chat's own property (
channels.web_chat.analytics.ga4) and its options, defaults filled in.7 attributes
measurement_idstring | nullrequiredapi_secret_setbooleanrequireddata_layerbooleanrequiredPush the funnel to the host page's dataLayer.
gtagbooleanrequiredCall the host page's gtag().
event_prefixstringrequiredPrepended to every event name. Default
chat_.require_consentbooleanrequiredpage_pathsstringrequiredOne of
sectionfull
effectiveobjectrequiredThe property server-side events go to now.
2 attributes
sourcestring | nullrequiredOne of
web_chatassistantmeasurement_idstring | nullrequired
statusobject | nullrequiredThe latest server-side hit; null before the first.
5 attributes
last_eventstringrequiredlast_statusstringrequiredOne of
deliveredrejectedunreachablenot_configuredno_identitylast_success_atstring | nullrequiredISO 8601 timestamplast_failure_atstring | nullrequiredISO 8601 timestamplast_failure_reasonstring | nullrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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_..."
}
}'{
"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
idstringrequiredAssistant id,
asst_....
Request body
measurement_idstringapi_secretstringup to 128 characterswrite-only, never returned
Returns
200 The test's outcome
Response attributes
dataobjectrequired6 attributes
validbooleanrequiredGA4's validator found nothing wrong.
messagesarray of stringrequiredWhat the validator objected to.
sentbooleanrequiredThe real event was accepted.
reasonstringWhy it was not valid or not sent.
One of
not_configuredno_identityrejectedunreachableevent_namestringrequiredmeasurement_idstring | nullrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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. CarriesRetry-After.
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_..."
}'{
"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 1expected_draft_revisionintegermin 0notestringup to 500 characters
Returns
200 OK
Response attributes
dataAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. Archived, no widget, chat or call serves it.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}'{
"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 AssistantVersionrequired8 attributes
assistant_idstringrequiredversionintegerrequirednamestringsourcestringrequiredOne of
createapi_editpublishrestorebulk_updateseedcreated_bystring | nullnotestring | nullcreated_atstringISO 8601 timestampconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/versions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredversionintegerrequired
Returns
200 OK
Response attributes
dataAssistantVersionrequired8 attributes
assistant_idstringrequiredversionintegerrequirednamestringsourcestringrequiredOne of
createapi_editpublishrestorebulk_updateseedcreated_bystring | nullnotestring | nullcreated_atstringISO 8601 timestampconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/assistants/ASSISTANT_ID/versions/VERSION" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredversionintegerrequired
Request body
targetstringOne of
draftliveDefault
"draft"expected_versionintegermin 1expected_draft_revisionintegermin 0
Returns
200 The draft it was restored into, or the assistant with target live.
Response attributes
dataAssistantDraft | null | AssistantrequiredOne of 2 shapes
AssistantDraft
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
assistant_idstringconfigAssistantConfigThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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 stringPaths that differ from live but read back the same: credentials and tool request specs. Values are never returned.
revisionintegerbase_versionintegerThe live version the draft started from.
live_versionintegerstalebooleanLive was edited after the draft started; publishing is refused.
updated_atstringISO 8601 timestamp
Assistant
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. Archived, no widget, chat or call serves it.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}'{
"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 emptywebsitestringup to 2048 charactersgoalstringrequiredOne of
leadsbookinganswersdescriptionstringup to 2000 characters
Returns
201 OK
Response attributes
dataWebsiteAssistantDraftrequired2 attributes
assistantAssistantrequired14 attributes
effective_hoursobjectrequiredEffective 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 | nullrequired3 attributes
daystringrequiredOne of
montuewedthufrisatsunopenstringrequiredclosestringrequired
sourcestring | nullrequiredOne of
assistantbusiness
effective_timezoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
effective_team_phoneobjectrequiredEffective 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 | nullrequiredsourcestring | nullrequiredOne of
assistantbusiness
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredconfigAssistantConfigrequiredThe 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 backapi_secret_set: truewhen its secret is stored, and a write that sendsapi_secretin 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
schedulingobjectEvents 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
versionintegerrequiredevent_type_idsarray of stringrequiredup to 100 items
agentobjectrequired1 attribute
instructionsstringrequired
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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
sessionanyrequired5 attributes
llmobject2 attributes
providerstringnot emptymodelstringrequirednot empty
realtimeobject2 attributes
providerstringrequirednot emptymodelstringnot empty
sttProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
ttsProviderModel2 attributes
providerstringrequirednot emptymodelstringrequirednot empty
toolsAssistantToolsCustom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.
1 attribute
definitionsarray of AssistantToolDefinition6 attributes
namestringrequireddescriptionstringparametersobjectJSON Schema for the arguments, as exposed to the model.
enabledbooleanFalse keeps the tool saved, with its request, but offers it on no channel.
Default
truechannelsarray of stringWhere the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both.
read_onlybooleanTrue 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 itemsAuthoring-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 characterslabelstringup to 120 charactersdescriptionstringup to 500 charactersdefaultstringup to 2000 characters
lead_captureobjectWhich lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type
string,emailorphone, required, options). When set it replaceschannels.web_chat.lead_captureas a whole object, with no field merge; that older key is still read when this one is absent.4 attributes
enabledbooleanpromptstringrequire_completebooleanfieldsarray of object5 attributes
keystringrequiredlabelstringtypestringOne of
stringemailphonenumberrequiredbooleanoptionsarray of stringup to 6 items
knowledgeobjectThe 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 bothchatandvoicefalse counts as detached. Changing it needs an org-wide key and editor access to each base: 403organization_knowledge_access_requiredfor a project key orknowledge_forbiddenwithout editor access, 400knowledge_base_not_foundfor an unknown id, 409knowledge_voice_requires_pipeline_assistantfor voice on a realtime session. Each refusal names the base inknowledge_base_id.3 attributes
chatbooleanrequiredSearch it in web chat and WhatsApp.
voicebooleanrequiredSearch it on calls. Needs a pipeline session, not realtime.
priorityintegerrequired0 to 100Each 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.
versionintegerrequireddraft_revisionintegerThe revision a draft save names as expected_draft_revision; 0 before the first draft.
draftobject | nullWhether a draft exists, without its config (GET /assistants/{id}/draft has it).
3 attributes
revisionintegerbase_versionintegerupdated_atstringISO 8601 timestamp
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamparchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. Archived, no widget, chat or call serves it.
draftobjectrequired7 attributes
generated_bystringrequiredOne of
modeltemplatewebsitestring | nullrequiredknowledge_base_idstring | nullrequiredpagesarray of objectrequired3 attributes
urlstringrequiredtitlestring | nullrequiredused_forarray of stringrequired
section_factsarray of object4 attributes
sectionstringrequiredfieldstringrequiredvalueanyrequiredsourcesarray of objectrequired2 attributes
urlstringrequiredsnippetstringrequired
factsobjectrequired7 attributes
business_namestring | nullrequiredservicesarray of stringrequiredhoursstring | nullrequiredphonestring | nullrequiredcoloursarray of stringrequiredlogostring | nullrequiredtime_zonestring | nullrequired
missingarray of stringrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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
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"
}'{
"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"
]
}
}
}