Sign in

v45

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-0114775543.6 KB
Agents

Create a new agent

Create a new agent by passing the agent name in the request body.

New agents have versioning enabled by default. To set the prompt, firstMessage, tools, or any runtime config, fork a draft from the auto-created initial version, edit it, publish, and activate — see the Versioning Lifecycle guide for the full flow.

The legacy PATCH /workflow/{workflowId} endpoint writes directly to the underlying workflow document and bypasses the version lifecycle; edits made that way are not captured as a version and may not propagate to live calls. Use the drafts flow above.

post/agent

Request body

namestring required
descriptionstring
backgroundSound'' | 'office' | 'cafe' | 'call_center' | 'static'

Ambient background sound during calls. Options: '' (none), 'office', 'cafe', 'call_center', 'static'. Note: this value is currently overridden by the server default on creation; update via PATCH after creation.

globalKnowledgeBaseIdstring

The global knowledge base ID of the agent. You can create a global knowledge base by using the /knowledgebase endpoint and assign it to the agent. The agent will use this knowledge base for its responses.

slmModel'electron' | 'electron-kogta' | 'electron-kogta-v2' | 'gpt-4o' | 'gpt-4.1' | 'gpt-5.2' | 'gpt-realtime' | 'gpt-realtime-mini'

The LLM model to use for the agent. Note: gpt-5.2, electron-kogta, and electron-kogta-v2 require org-level access and return 403 if not enabled. workflowType must be single_prompt to use gpt-realtime or gpt-realtime-mini.

defaultVariablesobject

The default variables to use for the agent. These variables will be used if no variables are provided when initiating a conversation with the agent.

globalPromptstring

Set global instructions for your agent's personality, role, and behavior throughout conversations. Note: Only used for workflow_graph agents. Maximum 4000 characters.

telephonyProductIdstring[]

IDs of telephony products (phone numbers) to associate with the agent for inbound/outbound calls.

workflowType'workflow_graph' | 'single_prompt'

The type of workflow configuration. workflow_graph uses a node-based visual workflow, single_prompt uses a simple prompt-based configuration.

firstMessagestring

The first message the agent sends when a conversation starts.

muteUserUntilFirstBotResponseboolean

When true, the user's audio is muted until the agent has finished its first response.

allowInterruptionsboolean

Whether the user can interrupt the agent while it is speaking.

waitForUserToSpeakFirstboolean

When true, the agent waits for the user to speak before sending the first message.

interruptionBackoffTimernumber

Seconds the agent waits after being interrupted before resuming speech.

callDispositionConfigstring

Configuration string for call disposition tracking.

allowInboundCallboolean

Whether the agent accepts inbound calls.

enableStyleGuideboolean

Whether style guide enforcement is applied to agent responses.

speechFormattingboolean

Whether speech formatting is applied to the agent's responses.

Response

Agent created successfully

statusboolean
datastring

The ID of the created agent

Example response

{
  "status": true,
  "data": "60d0fe4f5311236168a109ca"
}