Save brief
Store the agent's brief, the two interview answers that can be checked rather than just written down. `callReasons` is what people ring about. `nevers` is what the agent must never do, and each never must name the tool it forbids, because storing it also COMPILES it: the platform creates a scenario where a caller pushes three times for the forbidden thing, asserts `tool_not_called` against that tool, and links the scenario to the rule. A never that names no tool, or names a tool this version does not have, is REFUSED and nothing is stored, so ask the operator which action they mean instead of guessing, and read the tool list off get_agent rather than from memory. Removing a never from the list deletes its scenario too. Call this during the interview, before writing config: the answers persist on the draft version, so they survive into the next build and a later reader can see what the operator actually asked for. This records intent, it does not change how the agent behaves. Wire the behaviour itself with update_system_prompt and the matching set_* ops.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/operations/set_brief" \ -H "Content-Type: application/json" \ -d '{ "agent": "string" }'{}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Edit branding POST
Set the agent's caller-facing branding on `agents.settings.branding`: `displayName` (the business name shown on the request_details_form detail-capture page the caller fills in, as the website chat widget's header name, in the header of the agent's public share page, and on the staff transcript link of a website chat handoff) and `formMessage` (a short line under it on that form, used nowhere else). In the app both live under Business details on the agent's Channels tab. Pass only the field you want to change; an empty string or null clears it (the display name then falls back to the agent's name). Set this to the customer's trading name, a leftover onboarding placeholder is caller-visible whenever the agent texts a details form. The logo is uploaded separately and is not settable here.
Set builtin config POST
Set the builtin_config (template-specific settings) on a BUILTIN tool, for example take_a_message's message routing (default_recipient + per-category/person routing rules) or transfer_to_human's destination, announced person and transfer style (`screening`: none, press1 or the consult call), or call_and_connect's `stay_on_the_line` (true: the agent stays on the call with the caller and the person it rang), or end_call's `speak_farewell` (true: the agent's closing line goes in end_call's `farewell` argument and is spoken before the hang-up). Identify the tool by toolName (its snake_case name) or toolId. `config` is the FULL builtin_config as a JSON object string and REPLACES the existing config, so read the current one from get_agent, edit it, and send the whole object back. To change ONE take_a_message setting on a live agent, prefer the ops that merge instead of replace, set_take_message_sms (the text copy) and set_take_message_details (what every message records), so a missed read can't delete the routing table. Only builtin tools have a builtin_config; for HTTP tools use set_tool_endpoint / set_tool_headers / set_tool_params instead. The change lands on the draft version.