@laburen/delta-cli 0.2.0-canary.22 → 0.2.0-canary.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,14 +1,14 @@
1
1
  // GENERADO por scripts/generate-commands.mjs a partir de ../delta-sdk/contract/openapi.json. No editar a mano.
2
2
  /** Por operación con body: el JSON Schema de lo que se manda y de la respuesta, con los `$ref` ya resueltos. */
3
3
  export const OPERATION_SCHEMAS = {
4
- "agents.create": { "body": { "additionalProperties": false, "properties": { "activate": { "description": "Whether to make the new version the active one. Requires config. Defaults to true.", "type": "boolean" }, "config": { "additionalProperties": false, "description": "Config of the first version. When omitted, no version is created.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, "reply": { "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "required": ["model"], "type": "object" }, "description": { "default": "", "description": "What the agent is for. Defaults to an empty string.", "type": "string" }, "harness_type": { "const": "mastra", "description": "Runtime of the agent. Only `mastra` can be created through this API.", "type": "string" }, "mcp_connections": { "description": "MCP connections to assign. Requires config. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "name": { "description": "Name of the agent.", "minLength": 1, "type": "string" }, "skills": { "description": "Skills to assign. Requires config. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "required": ["harness_type", "name"], "type": "object" }, "response": { "properties": { "active_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the version that is running; `null` when none is active." }, "created_at": { "description": "When the agent was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "description": "What the agent is for.", "type": "string" }, "harness_type": { "description": "Runtime the agent runs on. Agents created through this API are `mastra`.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the agent.", "type": "string" }, "name": { "description": "Name of the agent.", "type": "string" }, "type": { "const": "agent", "description": "Object type, always `agent`.", "type": "string" }, "updated_at": { "description": "When the agent was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "version": { "anyOf": [{ "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`) or a version identical to the latest one (`no_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, or a version identical to the latest one.", "properties": { "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one.", "enum": ["mcp_tools_unverified", "no_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), or that the new version is identical to the latest one (`no_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" }, { "type": "null" }], "description": "The version this call created; `null` when it did not create one." } }, "required": ["type", "id", "name", "description", "harness_type", "active_version_id", "created_at", "updated_at", "version"], "type": "object" } },
4
+ "agents.create": { "body": { "additionalProperties": false, "properties": { "activate": { "description": "Whether to make the new version the active one. Requires config. Defaults to true.", "type": "boolean" }, "config": { "additionalProperties": false, "description": "Config of the first version. When omitted, no version is created.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, "reply": { "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "required": ["model"], "type": "object" }, "description": { "default": "", "description": "What the agent is for. Defaults to an empty string.", "type": "string" }, "harness_type": { "const": "mastra", "description": "Runtime of the agent. Only `mastra` can be created through this API.", "type": "string" }, "mcp_connections": { "description": "MCP connections to assign. Requires config. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "name": { "description": "Name of the agent.", "minLength": 1, "type": "string" }, "skills": { "description": "Skills to assign. Requires config. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "required": ["harness_type", "name"], "type": "object" }, "response": { "properties": { "active_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the version that is running; `null` when none is active." }, "created_at": { "description": "When the agent was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "description": "What the agent is for.", "type": "string" }, "harness_type": { "description": "Runtime the agent runs on. Agents created through this API are `mastra`.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the agent.", "type": "string" }, "name": { "description": "Name of the agent.", "type": "string" }, "type": { "const": "agent", "description": "Object type, always `agent`.", "type": "string" }, "updated_at": { "description": "When the agent was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "version": { "anyOf": [{ "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`), a version identical to the latest one (`no_changes`) or a version that carries unpublished changes of a latest version that is not active (`includes_unpublished_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, a version identical to the latest one, or a version built on a latest version that is not active.", "properties": { "active_version_id": { "description": "Id of the version that was active when this one was created; only on `includes_unpublished_changes`.", "type": "string" }, "changed_fields_from_active": { "description": "Config paths that differ between the active version and the new one, named like `changed_fields`; only on `includes_unpublished_changes`.", "items": { "type": "string" }, "type": "array" }, "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one. `includes_unpublished_changes`: the new version was built on the latest version, which is not the active one, so it carries that version's unpublished changes.", "enum": ["mcp_tools_unverified", "no_changes", "includes_unpublished_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), that the new version is identical to the latest one (`no_changes`), or which fields differ from the active version and that they should be compared before activating (`includes_unpublished_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" }, { "type": "null" }], "description": "The version this call created; `null` when it did not create one." } }, "required": ["type", "id", "name", "description", "harness_type", "active_version_id", "created_at", "updated_at", "version"], "type": "object" } },
5
5
  "agents.generate": { "body": { "additionalProperties": false, "properties": { "contact": { "additionalProperties": false, "description": "Profile of the end user, used only when `memory.resource` creates a new contact.", "properties": { "email": { "description": "Email of the end user. If another contact of the organization already uses it, the contact is created without it.", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "type": "string" }, "first_name": { "description": "First name of the end user.", "type": "string" }, "last_name": { "description": "Last name of the end user.", "type": "string" }, "phone_number": { "description": "Phone number of the end user. If another contact of the organization already uses it, the contact is created without it.", "type": "string" } }, "type": "object" }, "context": { "description": "Extra texts the model should know in this run. They are joined with a blank line and put before the message.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "Runs the turn with the evals accounts of the model providers and marks the conversation as evals. Azure models run as the same model on OpenRouter, with the evals account. It never runs on production: a model with no evals route returns 400 `evals_not_supported` (see `capabilities.evals` in `models.list`). Omit it, or send `null`, for production. A conversation keeps the environment it was created with: a turn with a different one returns 400 `invalid_request` with `details.reason` `environment_mismatch` and `details.thread_environment` set to the environment of the conversation (`evals` or `null`). Needs only the `query` permission." }, "instructions": { "description": "Replaces the prompt of the agent for this run only. Requires the `write` permission.", "minLength": 1, "type": "string" }, "max_steps": { "default": 80, "description": "Maximum number of model steps in the run (1 to 200). Requires the `write` permission.", "maximum": 200, "minimum": 1, "type": "integer" }, "memory": { "additionalProperties": false, "description": "Which conversation the turn belongs to and who the end user is.", "properties": { "resource": { "description": "Your own id for the end user (for example a customer id). The server creates or reuses the contact of that user.", "maxLength": 255, "minLength": 1, "type": "string" }, "thread": { "description": "A conversation id returned by a previous run; omit it to start a new conversation. It must belong to this agent.", "minLength": 1, "type": "string" } }, "type": "object" }, "messages": { "anyOf": [{ "minLength": 1, "type": "string" }, { "items": { "description": "A message of the user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. Text parts are joined with a blank line.", "items": { "anyOf": [{ "description": "A piece of text of the message.", "properties": { "text": { "description": "The text of the part.", "type": "string" }, "type": { "const": "text", "description": "Part type, always `text`.", "type": "string" } }, "required": ["type", "text"], "type": "object" }, { "description": "A file attached to the message.", "properties": { "filename": { "description": "Name of the file. If omitted, the last segment of the URL is used.", "type": "string" }, "media_type": { "description": "MIME type of the file, for example `application/pdf` or `image/png`. It must match the file content: if the content is recognizably of another type (for example a PNG declared as `application/pdf`), the request fails with `invalid_request` and `details.reason` `media_type_mismatch`.", "minLength": 1, "type": "string" }, "type": { "const": "file", "description": "Part type, always `file`.", "type": "string" }, "url": { "description": "Public `https` URL of the file. The server downloads it before the turn starts; the file can be up to 20 MB.", "format": "uri", "type": "string" } }, "required": ["type", "url", "media_type"], "type": "object" }] }, "minItems": 1, "type": "array" }, "role": { "const": "user", "description": "Author of the message, always `user`.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, "minItems": 1, "type": "array" }], "description": "What the user says: a plain string, or a list of user messages with text and file parts. The text of all the parts is joined with a blank line. A message with files and no text is valid; one with neither is rejected." }, "model": { "description": "Replaces the model of the agent for this run only. It must be one of the offered models. A model that reasons cannot run a version that has the `thinking` tool: 400 `invalid_request` with `details.reason` `thinking_tool_conflict` (see `capabilities.thinking_tool` in `models.list`). Requires the `write` permission.", "minLength": 1, "type": "string" }, "model_settings": { "additionalProperties": false, "description": "Model settings for this run only. Only `reasoning` is accepted; any other key is rejected. Requires the `write` permission.", "properties": { "reasoning": { "description": "Reasoning effort for this run. It must be a level the model supports; a model that reasons on a version with the `thinking` tool returns 400 `invalid_request` with `details.reason` `thinking_tool_conflict`. Requires the `write` permission.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "type": "object" }, "versions": { "additionalProperties": false, "description": "Runs a specific version instead of the active one. Needs only the `query` permission.", "properties": { "agents": { "additionalProperties": { "additionalProperties": false, "description": "The version to run.", "properties": { "version_id": { "description": "Id of the version to run. A version of this agent.", "minLength": 1, "type": "string" } }, "required": ["version_id"], "type": "object" }, "description": "Versions to run, keyed by agent id. The only key allowed is the agent being called.", "propertyNames": { "type": "string" }, "type": "object" } }, "required": ["agents"], "type": "object" } }, "required": ["messages"], "type": "object" }, "response": { "properties": { "cost": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "Credits the run cost; `null` when it was not charged." }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "The environment the turn ran in: `evals`, or `null` for production. It is the environment of the conversation (see `environment` in the request)." }, "files": { "description": "Files the agent sent in the run.", "items": { "description": "A file the agent sent.", "properties": { "media_type": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "MIME type of the file." }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Name of the file." }, "url": { "description": "URL of the file.", "type": "string" } }, "required": ["url", "media_type", "name"], "type": "object" }, "type": "array" }, "finish_reason": { "description": "Why the run ended.", "enum": ["stop", "length", "content-filter", "tool-calls", "error", "other"], "type": "string" }, "guardrail": { "anyOf": [{ "properties": { "decision_ids": { "description": "Ids of the decisions the guardrail saved in this turn, one per decision model it asked. Read them with `decisions.get` to see what it decided; empty if they could not be saved.", "items": { "type": "string" }, "type": "array" }, "triggered_rule": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The rule of `config.guardrails` that fired: then the agent did not run and `text` is its reply. `null` when the guardrail ran and no rule fired." } }, "required": ["triggered_rule", "decision_ids"], "type": "object" }, { "type": "null" }], "description": "What the input guardrail did in this turn; `null` when the agent has no guardrail or it did not run." }, "handoff": { "description": "Whether the agent asked to hand the conversation to a person.", "type": "boolean" }, "memory": { "description": "The conversation the run belongs to.", "properties": { "resource": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The `memory.resource` of the request; `null` when it was not sent." }, "thread": { "description": "Id of the conversation. Send it as `memory.thread` to continue it.", "type": "string" } }, "required": ["thread", "resource"], "type": "object" }, "message_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the stored message with the answer; `null` when nothing was stored." }, "reasoning_text": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Reasoning of the model, if it produced any; `null` otherwise." }, "run_id": { "description": "Id of the run.", "type": "string" }, "sources": { "description": "Knowledge sources the answer used.", "items": { "description": "A knowledge source the answer used.", "properties": { "chunk_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the chunk that was cited." }, "datasource_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the datasource the chunk comes from." }, "datasource_name": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Name of the datasource." }, "datastore_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the datastore the chunk comes from." }, "mime_type": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "MIME type of the source." }, "score": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "Relevance score of the chunk." }, "source_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the source." } }, "required": ["chunk_id", "datastore_id", "datasource_id", "datasource_name", "source_url", "mime_type", "score"], "type": "object" }, "type": "array" }, "text": { "description": "The answer of the agent.", "type": "string" }, "tool_calls": { "description": "Every tool the model called in the run.", "items": { "description": "A tool call of the run.", "properties": { "args": { "description": "Arguments the model sent to the tool." }, "tool_call_id": { "description": "Id of the tool call.", "type": "string" }, "tool_name": { "description": "Name of the tool the model called.", "type": "string" } }, "required": ["tool_call_id", "tool_name", "args"], "type": "object" }, "type": "array" }, "tool_results": { "description": "The result of each tool call that finished.", "items": { "description": "The result of a tool call.", "properties": { "is_error": { "description": "Whether the tool failed.", "type": "boolean" }, "result": { "description": "What the tool returned, or its error message when it failed." }, "tool_call_id": { "description": "Id of the tool call this result belongs to.", "type": "string" }, "tool_name": { "description": "Name of the tool.", "type": "string" } }, "required": ["tool_call_id", "tool_name", "result", "is_error"], "type": "object" }, "type": "array" }, "total_usage": { "description": "Tokens used, summed over the steps of the run.", "properties": { "cached_input_tokens": { "description": "Input tokens served from cache, of all the steps.", "type": "number" }, "input_tokens": { "description": "Input tokens of all the steps.", "type": "number" }, "output_tokens": { "description": "Output tokens of all the steps.", "type": "number" }, "reasoning_tokens": { "description": "Reasoning tokens of all the steps.", "type": "number" } }, "required": ["input_tokens", "output_tokens", "cached_input_tokens", "reasoning_tokens"], "type": "object" }, "trace_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the trace of the run in the observability tool; `null` when there is none." }, "type": { "const": "agent_run", "description": "Object type, always `agent_run`.", "type": "string" } }, "required": ["type", "text", "reasoning_text", "tool_calls", "tool_results", "sources", "files", "finish_reason", "total_usage", "trace_id", "run_id", "memory", "environment", "message_id", "cost", "handoff", "guardrail"], "type": "object" } },
6
6
  "agents.generateFollowUp": { "body": { "additionalProperties": false, "description": "A follow-up to simulate on a disposable copy of a conversation.", "properties": { "drafts": { "additionalProperties": false, "description": "Drafts for this run only: no version is created. They are saved in the attempt with the result. Requires the `write` permission when it has at least one key; `{}` does not.", "properties": { "decider_prompt": { "description": "Replaces `follow_up.decider.prompt` for this run only.", "minLength": 1, "type": "string" }, "instructions": { "description": "Replaces `follow_up.instructions` for this run only.", "minLength": 1, "type": "string" }, "step_instructions": { "description": "Replaces the instructions of the simulated step for this run only.", "minLength": 1, "type": "string" } }, "type": "object" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "Runs the filter and the agent with the evals accounts of the model providers and creates the disposable copy as evals. Azure models run as the same model on OpenRouter, with the evals account. It never runs on production: a model with no evals route returns 400 `evals_not_supported` (see `capabilities.evals` in `models.list`). Omit it, or send `null`, for production. A `thread` keeps the environment it was created with: a run with a different one returns 400 `invalid_request` with `details.reason` `environment_mismatch` and `details.thread_environment` set to the environment of the conversation (`evals` or `null`). Needs only the `query` permission." }, "messages": { "description": "A conversation written by you, oldest first. Send exactly one of `thread` and `messages`.", "items": { "additionalProperties": false, "description": "A message of the conversation.", "properties": { "created_at": { "description": "When the message was written. Send it in all the messages or in none, and each one at or after the previous one; otherwise the request is rejected with `invalid_request` and `details.field` `messages[i].created_at`. Without it, the messages go one after the other, ending now (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "parts": { "description": "Content of the message: text parts only, in order; file parts are rejected. Text parts are joined with a blank line.", "items": { "description": "A piece of text of the message.", "properties": { "text": { "description": "The text of the part.", "type": "string" }, "type": { "const": "text", "description": "Part type, always `text`.", "type": "string" } }, "required": ["type", "text"], "type": "object" }, "minItems": 1, "type": "array" }, "role": { "description": "Who wrote the message: `user` (the customer) or `assistant` (the agent).", "enum": ["user", "assistant"], "type": "string" } }, "required": ["role", "parts"], "type": "object" }, "minItems": 1, "type": "array" }, "mode": { "default": "both", "description": "What to run: `decider` (only the filter), `agent` (skips the filter) or `both`. In `both` the agent writes even if the filter says no, and then it does not get the filter's classification.", "enum": ["decider", "agent", "both"], "type": "string" }, "step": { "default": 1, "description": "Which step of `follow_up.steps` to simulate (1 to 3). Its instructions are used.", "maximum": 3, "minimum": 1, "type": "integer" }, "thread": { "description": "Id of a conversation of this agent to copy, from any channel (it can be a production one). The original is not changed. Send exactly one of `thread` and `messages`.", "minLength": 1, "type": "string" }, "versions": { "additionalProperties": false, "description": "Runs a specific version instead of the active one. Needs only the `query` permission.", "properties": { "agents": { "additionalProperties": { "additionalProperties": false, "description": "The version to run.", "properties": { "version_id": { "description": "Id of the version to run. A version of this agent.", "minLength": 1, "type": "string" } }, "required": ["version_id"], "type": "object" }, "description": "Versions to run, keyed by agent id. The only key allowed is the agent being called.", "propertyNames": { "type": "string" }, "type": "object" } }, "required": ["agents"], "type": "object" } }, "type": "object" }, "response": { "description": "The result of a simulated follow-up.", "properties": { "agent": { "anyOf": [{ "properties": { "category": { "anyOf": [{ "description": "Category of the decision, from the fixed list of `follow_up.reasons[].category`.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, { "type": "null" }], "description": "Category the agent declared; `null` when it did not call `decide_follow_up`." }, "child_reason": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The more specific reason the agent declared, from `follow_up.reasons`; `null` when none." }, "cost": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "Credits the turn of the agent cost; `null` when it was not charged." }, "decision": { "description": "Whether to send the follow-up (`send`) or not (`skip`). It comes from the group of the category.", "enum": ["send", "skip"], "type": "string" }, "declared": { "description": "Whether the agent called `decide_follow_up`. When it did not, the follow-up is sent.", "type": "boolean" }, "files": { "description": "Files the agent sent in the run.", "items": { "description": "A file the agent sent.", "properties": { "media_type": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "MIME type of the file." }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Name of the file." }, "url": { "description": "URL of the file.", "type": "string" } }, "required": ["url", "media_type", "name"], "type": "object" }, "type": "array" }, "messages": { "description": "The messages the agent would send; empty when it decided not to send.", "items": { "description": "A message.", "type": "string" }, "type": "array" }, "model": { "description": "The model that answered, named as its provider names it (for example `openai/gpt-5-mini`). It can differ from the model `id` of `models.list`.", "type": "string" }, "reason": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Why the agent decided it; `null` when it did not call `decide_follow_up`." }, "tool_calls": { "description": "Every tool the model called in the run.", "items": { "description": "A tool call of the run.", "properties": { "args": { "description": "Arguments the model sent to the tool." }, "tool_call_id": { "description": "Id of the tool call.", "type": "string" }, "tool_name": { "description": "Name of the tool the model called.", "type": "string" } }, "required": ["tool_call_id", "tool_name", "args"], "type": "object" }, "type": "array" }, "trace_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the trace of the turn in the observability tool; `null` when there is none." } }, "required": ["decision", "declared", "category", "child_reason", "reason", "messages", "files", "tool_calls", "model", "cost", "trace_id"], "type": "object" }, { "type": "null" }], "description": "What the agent decided and wrote; `null` in `decider` mode or when its turn failed (see `error`)." }, "attempt_id": { "description": "Id of the attempt saved in the follow-up log, marked as a test.", "type": "string" }, "cost": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "Credits of the whole run; `null` when nothing was charged." }, "decider": { "anyOf": [{ "properties": { "category": { "description": "Category of the decision, from the fixed list of `follow_up.reasons[].category`.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "child_reason": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The more specific reason of the agent the filter chose, from `follow_up.reasons`; `null` when it chose a category directly." }, "confidence": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "From 0 to 1: the probabilities of every option that leads to the same decision, added up. `null` when the model does not return probabilities." }, "cost": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "Credits the filter cost; `null` when it was not charged." }, "decision": { "description": "Whether to send the follow-up (`send`) or not (`skip`). It comes from the group of the category.", "enum": ["send", "skip"], "type": "string" }, "decision_id": { "description": "Id of the decision the filter saved; open it with `decisions.get`.", "type": "string" }, "model": { "description": "The decision model that answered: `jev-1.14.0` or `gemini-decision-1`.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt_source": { "description": "Which criteria the filter read: the draft of this run, the one saved in the version, or the default.", "enum": ["draft", "version", "default"], "type": "string" } }, "required": ["decision", "category", "child_reason", "confidence", "model", "decision_id", "prompt_source", "cost"], "type": "object" }, { "type": "null" }], "description": "What the filter decided; `null` in `agent` mode." }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "The environment the follow-up ran in: `evals`, or `null` for production. It is the `environment` of the request." }, "error": { "anyOf": [{ "properties": { "code": { "description": "Stable code of the error. Branch on this, not on the message.", "enum": ["credits_exhausted", "payment_overdue", "agent_unavailable", "unsupported_trigger", "model_provider_auth_failed", "model_provider_rate_limited", "model_provider_unavailable", "channel_provider_unavailable", "turn_deadline_exceeded", "model_response_malformed", "invalid_history", "tool_source_failed", "mcp_server_unreachable", "invalid_agent_config", "agent_not_found", "decision_not_found", "config_version_not_found", "version_number_conflict", "skill_not_found", "skill_version_not_found", "skill_name_taken", "invalid_skill", "internal_invariant_violation", "delivery_failed", "tool_execution_failed", "invalid_request", "model_context_exceeded", "model_content_filtered", "legacy_agent_not_supported", "mcp_connection_not_found", "mcp_connection_version_not_found", "version_in_use", "resource_in_use", "invalid_token", "organization_access_denied", "insufficient_permissions", "token_not_found", "idempotency_key_reused", "idempotency_key_in_progress", "invalid_origin", "base_version_mismatch", "mcp_connection_name_taken", "conversation_not_found", "channel_conversation_not_found", "thread_resource_mismatch", "ai_disabled_for_conversation", "conversational_mode_not_supported", "evals_not_supported", "rate_limited", "widget_not_found", "invalid_identity_token", "identity_required"], "type": "string" }, "details": { "additionalProperties": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "items": { "type": "string" }, "type": "array" }, { "items": { "additionalProperties": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }] }, "propertyNames": { "type": "string" }, "type": "object" }, "type": "array" }] }, "description": "Extra data about the error; its keys depend on the code.", "propertyNames": { "type": "string" }, "type": "object" }, "message": { "description": "Human-readable explanation of what went wrong and how to fix it.", "type": "string" }, "type": { "description": "Error family; it decides the HTTP status.", "enum": ["invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "conflict_error", "rate_limit_error", "api_error", "overloaded_error"], "type": "string" } }, "required": ["type", "code", "message", "details"], "type": "object" }, { "type": "null" }], "description": "In `both` mode, the error of the turn of the agent when it fails after the filter decided, with `details.stage` `agent`; `outcome` is `failed`, or `skipped` if the filter said no. `null` otherwise. Any other failure is an error response, and the errors of the filter or of the agent carry `details.stage` (`decider` or `agent`). The errors of the filter also carry `details.decision_id`: the failed decision was saved, open it with `decisions.get`." }, "outcome": { "description": "`would_send`: the follow-up would go out. `skipped`: the filter or the agent decided not to send it. `failed`: the agent decided to send it but wrote nothing, or its turn failed (see `error`).", "enum": ["would_send", "skipped", "failed"], "type": "string" }, "stopped_by": { "anyOf": [{ "enum": ["decider", "agent"], "type": "string" }, { "type": "null" }], "description": "Who decided not to send it; `null` when nobody stopped it." }, "type": { "const": "follow_up_run", "description": "Object type, always `follow_up_run`.", "type": "string" } }, "required": ["type", "attempt_id", "outcome", "stopped_by", "decider", "agent", "environment", "cost", "error"], "type": "object" } },
7
7
  "agents.sendMessage": { "body": { "additionalProperties": false, "description": "Run overrides (`instructions`, `model`, `versions`, `environment`, and the like) are not accepted here: the agent answers several queued messages with one turn, and a batch joins messages from several requests.", "properties": { "contact": { "additionalProperties": false, "description": "Profile of the end user, used only when `memory.resource` creates a new contact.", "properties": { "email": { "description": "Email of the end user. If another contact of the organization already uses it, the contact is created without it.", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "type": "string" }, "first_name": { "description": "First name of the end user.", "type": "string" }, "last_name": { "description": "Last name of the end user.", "type": "string" }, "phone_number": { "description": "Phone number of the end user. If another contact of the organization already uses it, the contact is created without it.", "type": "string" } }, "type": "object" }, "memory": { "additionalProperties": false, "description": "Which conversation the turn belongs to and who the end user is.", "properties": { "resource": { "description": "Your own id for the end user (for example a customer id). The server creates or reuses the contact of that user.", "maxLength": 255, "minLength": 1, "type": "string" }, "thread": { "description": "A conversation id returned by a previous run; omit it to start a new conversation. It must belong to this agent.", "minLength": 1, "type": "string" } }, "type": "object" }, "messages": { "anyOf": [{ "minLength": 1, "type": "string" }, { "items": { "description": "A message of the user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. Text parts are joined with a blank line.", "items": { "anyOf": [{ "description": "A piece of text of the message.", "properties": { "text": { "description": "The text of the part.", "type": "string" }, "type": { "const": "text", "description": "Part type, always `text`.", "type": "string" } }, "required": ["type", "text"], "type": "object" }, { "description": "A file attached to the message.", "properties": { "filename": { "description": "Name of the file. If omitted, the last segment of the URL is used.", "type": "string" }, "media_type": { "description": "MIME type of the file, for example `application/pdf` or `image/png`. It must match the file content: if the content is recognizably of another type (for example a PNG declared as `application/pdf`), the request fails with `invalid_request` and `details.reason` `media_type_mismatch`.", "minLength": 1, "type": "string" }, "type": { "const": "file", "description": "Part type, always `file`.", "type": "string" }, "url": { "description": "Public `https` URL of the file. The server downloads it before the turn starts; the file can be up to 20 MB.", "format": "uri", "type": "string" } }, "required": ["type", "url", "media_type"], "type": "object" }] }, "minItems": 1, "type": "array" }, "role": { "const": "user", "description": "Author of the message, always `user`.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, "minItems": 1, "type": "array" }], "description": "What the user says: a plain string, or a list of user messages with text and file parts. The text of all the parts is joined with a blank line. A message with files and no text is valid; one with neither is rejected." }, "webhook_url": { "description": "Public `https` URL that receives the answer. The server sends a POST with the header `X-Laburen-Event`: `agent.response` with the answer, or `agent.error` if the turn fails; their headers and bodies are the outgoing events `agent.response` and `agent.error` of the contract (the `webhooks` of the OpenAPI document). Both add `message_ids`: the ids of the messages the turn answers. There is no signature and no retry; a webhook that does not answer within 30 seconds is skipped. Any `webhook_url` that is not a public `https` URL (not a URL at all, another protocol, a private or local host) returns 400 `invalid_request` with `details.reason` `invalid_webhook_url`. If several messages of one conversation are batched, the `webhook_url` of the newest one receives the answer.", "type": "string" } }, "required": ["messages", "webhook_url"], "type": "object" }, "response": { "description": "The message was stored and queued. The answer is not in this response: it arrives at the `webhook_url`.", "properties": { "memory": { "description": "The conversation the message belongs to.", "properties": { "resource": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The `memory.resource` of the request, or the one that owns the thread; `null` when there is none." }, "thread": { "description": "Id of the conversation. Send it as `memory.thread` to continue it.", "type": "string" } }, "required": ["thread", "resource"], "type": "object" }, "message_id": { "description": "Id of the stored message of the user.", "type": "string" }, "type": { "const": "queued_message", "description": "Object type, always `queued_message`.", "type": "string" } }, "required": ["type", "message_id", "memory"], "type": "object" } },
8
8
  "agents.stream": { "body": { "additionalProperties": false, "properties": { "contact": { "additionalProperties": false, "description": "Profile of the end user, used only when `memory.resource` creates a new contact.", "properties": { "email": { "description": "Email of the end user. If another contact of the organization already uses it, the contact is created without it.", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "type": "string" }, "first_name": { "description": "First name of the end user.", "type": "string" }, "last_name": { "description": "Last name of the end user.", "type": "string" }, "phone_number": { "description": "Phone number of the end user. If another contact of the organization already uses it, the contact is created without it.", "type": "string" } }, "type": "object" }, "context": { "description": "Extra texts the model should know in this run. They are joined with a blank line and put before the message.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "Runs the turn with the evals accounts of the model providers and marks the conversation as evals. Azure models run as the same model on OpenRouter, with the evals account. It never runs on production: a model with no evals route returns 400 `evals_not_supported` (see `capabilities.evals` in `models.list`). Omit it, or send `null`, for production. A conversation keeps the environment it was created with: a turn with a different one returns 400 `invalid_request` with `details.reason` `environment_mismatch` and `details.thread_environment` set to the environment of the conversation (`evals` or `null`). Needs only the `query` permission." }, "instructions": { "description": "Replaces the prompt of the agent for this run only. Requires the `write` permission.", "minLength": 1, "type": "string" }, "max_steps": { "default": 80, "description": "Maximum number of model steps in the run (1 to 200). Requires the `write` permission.", "maximum": 200, "minimum": 1, "type": "integer" }, "memory": { "additionalProperties": false, "description": "Which conversation the turn belongs to and who the end user is.", "properties": { "resource": { "description": "Your own id for the end user (for example a customer id). The server creates or reuses the contact of that user.", "maxLength": 255, "minLength": 1, "type": "string" }, "thread": { "description": "A conversation id returned by a previous run; omit it to start a new conversation. It must belong to this agent.", "minLength": 1, "type": "string" } }, "type": "object" }, "messages": { "anyOf": [{ "minLength": 1, "type": "string" }, { "items": { "description": "A message of the user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. Text parts are joined with a blank line.", "items": { "anyOf": [{ "description": "A piece of text of the message.", "properties": { "text": { "description": "The text of the part.", "type": "string" }, "type": { "const": "text", "description": "Part type, always `text`.", "type": "string" } }, "required": ["type", "text"], "type": "object" }, { "description": "A file attached to the message.", "properties": { "filename": { "description": "Name of the file. If omitted, the last segment of the URL is used.", "type": "string" }, "media_type": { "description": "MIME type of the file, for example `application/pdf` or `image/png`. It must match the file content: if the content is recognizably of another type (for example a PNG declared as `application/pdf`), the request fails with `invalid_request` and `details.reason` `media_type_mismatch`.", "minLength": 1, "type": "string" }, "type": { "const": "file", "description": "Part type, always `file`.", "type": "string" }, "url": { "description": "Public `https` URL of the file. The server downloads it before the turn starts; the file can be up to 20 MB.", "format": "uri", "type": "string" } }, "required": ["type", "url", "media_type"], "type": "object" }] }, "minItems": 1, "type": "array" }, "role": { "const": "user", "description": "Author of the message, always `user`.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, "minItems": 1, "type": "array" }], "description": "What the user says: a plain string, or a list of user messages with text and file parts. The text of all the parts is joined with a blank line. A message with files and no text is valid; one with neither is rejected." }, "model": { "description": "Replaces the model of the agent for this run only. It must be one of the offered models. A model that reasons cannot run a version that has the `thinking` tool: 400 `invalid_request` with `details.reason` `thinking_tool_conflict` (see `capabilities.thinking_tool` in `models.list`). Requires the `write` permission.", "minLength": 1, "type": "string" }, "model_settings": { "additionalProperties": false, "description": "Model settings for this run only. Only `reasoning` is accepted; any other key is rejected. Requires the `write` permission.", "properties": { "reasoning": { "description": "Reasoning effort for this run. It must be a level the model supports; a model that reasons on a version with the `thinking` tool returns 400 `invalid_request` with `details.reason` `thinking_tool_conflict`. Requires the `write` permission.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "type": "object" }, "versions": { "additionalProperties": false, "description": "Runs a specific version instead of the active one. Needs only the `query` permission.", "properties": { "agents": { "additionalProperties": { "additionalProperties": false, "description": "The version to run.", "properties": { "version_id": { "description": "Id of the version to run. A version of this agent.", "minLength": 1, "type": "string" } }, "required": ["version_id"], "type": "object" }, "description": "Versions to run, keyed by agent id. The only key allowed is the agent being called.", "propertyNames": { "type": "string" }, "type": "object" } }, "required": ["agents"], "type": "object" } }, "required": ["messages"], "type": "object" }, "response": null },
9
- "agents.update": { "body": { "additionalProperties": false, "properties": { "activate": { "description": "Whether to make the new version the active one. Only applies when a version is created. Defaults to false.", "type": "boolean" }, "base_version_id": { "anyOf": [{ "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Id of the version you based this change on. If it is not the latest version, the call fails with 409 `base_version_mismatch` and `details.latest_version_id`. Send `null` to say the resource has no versions yet; omit it to skip the check." }, "change_message": { "description": "Note stored with the new version. Used only when a version is created.", "type": "string" }, "config": { "additionalProperties": false, "description": "Changes to the config. Creates a new version.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "anyOf": [{ "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, { "type": "null" }], "description": "How the agent handles files sent by the user. `null` removes it." }, "follow_up": { "anyOf": [{ "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, { "type": "null" }], "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels. `null` removes it." }, "guardrails": { "anyOf": [{ "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, { "type": "null" }], "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally. `null` removes it." }, "history": { "anyOf": [{ "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, { "type": "null" }], "description": "How much of the conversation is sent to the model. `null` removes it." }, "inbound": { "anyOf": [{ "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, { "type": "null" }], "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`. `null` removes it." }, "knowledge": { "anyOf": [{ "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" }], "description": "Knowledge the agent can search. `null` removes it." }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "anyOf": [{ "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, { "type": "null" }], "description": "System prompt, as a list of blocks. `null` removes it." }, "reply": { "anyOf": [{ "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, { "type": "null" }], "description": "How the agent's reply goes out. `null` removes it." }, "tools": { "anyOf": [{ "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" }, { "type": "null" }], "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`. `null` removes it." } }, "type": "object" }, "description": { "description": "New description of the agent.", "type": "string" }, "mcp_connections": { "description": "Replaces the assigned MCP connections. Creates a new version. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "name": { "description": "New name of the agent.", "minLength": 1, "type": "string" }, "skills": { "description": "Replaces the assigned skills. Creates a new version. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "type": "object" }, "response": { "properties": { "active_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the version that is running; `null` when none is active." }, "created_at": { "description": "When the agent was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "description": "What the agent is for.", "type": "string" }, "harness_type": { "description": "Runtime the agent runs on. Agents created through this API are `mastra`.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the agent.", "type": "string" }, "name": { "description": "Name of the agent.", "type": "string" }, "type": { "const": "agent", "description": "Object type, always `agent`.", "type": "string" }, "updated_at": { "description": "When the agent was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "version": { "anyOf": [{ "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`) or a version identical to the latest one (`no_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, or a version identical to the latest one.", "properties": { "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one.", "enum": ["mcp_tools_unverified", "no_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), or that the new version is identical to the latest one (`no_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" }, { "type": "null" }], "description": "The version this call created; `null` when it did not create one." } }, "required": ["type", "id", "name", "description", "harness_type", "active_version_id", "created_at", "updated_at", "version"], "type": "object" } },
10
- "agents.versions.create": { "body": { "additionalProperties": false, "properties": { "base_version_id": { "anyOf": [{ "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Id of the version you based this change on. If it is not the latest version, the call fails with 409 `base_version_mismatch` and `details.latest_version_id`. Send `null` to say the resource has no versions yet; omit it to skip the check." }, "change_message": { "description": "Note stored with the version.", "type": "string" }, "config": { "additionalProperties": false, "description": "Config to create an agent version. `model` is required; omitted keys use their defaults.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, "reply": { "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "required": ["model"], "type": "object" }, "mcp_connections": { "description": "MCP connections to assign. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills to assign. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "required": ["config"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`) or a version identical to the latest one (`no_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, or a version identical to the latest one.", "properties": { "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one.", "enum": ["mcp_tools_unverified", "no_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), or that the new version is identical to the latest one (`no_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" } },
11
- "agents.versions.restore": { "body": { "additionalProperties": false, "properties": { "activate": { "default": true, "description": "Whether to make the restored copy the active version. Defaults to true.", "type": "boolean" } }, "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`) or a version identical to the latest one (`no_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, or a version identical to the latest one.", "properties": { "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one.", "enum": ["mcp_tools_unverified", "no_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), or that the new version is identical to the latest one (`no_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" } },
9
+ "agents.update": { "body": { "additionalProperties": false, "properties": { "activate": { "description": "Whether to make the new version the active one. Only applies when a version is created. Defaults to false.", "type": "boolean" }, "base_version_id": { "anyOf": [{ "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Id of the version you based this change on. If it is not the latest version, the call fails with 409 `base_version_mismatch` and `details.latest_version_id`. Send `null` to say the resource has no versions yet; omit it to skip the check." }, "change_message": { "description": "Note stored with the new version. Used only when a version is created.", "type": "string" }, "config": { "additionalProperties": false, "description": "Changes to the config. Creates a new version.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "anyOf": [{ "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, { "type": "null" }], "description": "How the agent handles files sent by the user. `null` removes it." }, "follow_up": { "anyOf": [{ "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, { "type": "null" }], "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels. `null` removes it." }, "guardrails": { "anyOf": [{ "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, { "type": "null" }], "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally. `null` removes it." }, "history": { "anyOf": [{ "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, { "type": "null" }], "description": "How much of the conversation is sent to the model. `null` removes it." }, "inbound": { "anyOf": [{ "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, { "type": "null" }], "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`. `null` removes it." }, "knowledge": { "anyOf": [{ "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" }], "description": "Knowledge the agent can search. `null` removes it." }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "anyOf": [{ "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, { "type": "null" }], "description": "System prompt, as a list of blocks. `null` removes it." }, "reply": { "anyOf": [{ "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, { "type": "null" }], "description": "How the agent's reply goes out. `null` removes it." }, "tools": { "anyOf": [{ "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" }, { "type": "null" }], "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`. `null` removes it." } }, "type": "object" }, "description": { "description": "New description of the agent.", "type": "string" }, "mcp_connections": { "description": "Replaces the assigned MCP connections. Creates a new version. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "name": { "description": "New name of the agent.", "minLength": 1, "type": "string" }, "skills": { "description": "Replaces the assigned skills. Creates a new version. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "type": "object" }, "response": { "properties": { "active_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the version that is running; `null` when none is active." }, "created_at": { "description": "When the agent was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "description": "What the agent is for.", "type": "string" }, "harness_type": { "description": "Runtime the agent runs on. Agents created through this API are `mastra`.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the agent.", "type": "string" }, "name": { "description": "Name of the agent.", "type": "string" }, "type": { "const": "agent", "description": "Object type, always `agent`.", "type": "string" }, "updated_at": { "description": "When the agent was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "version": { "anyOf": [{ "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`), a version identical to the latest one (`no_changes`) or a version that carries unpublished changes of a latest version that is not active (`includes_unpublished_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, a version identical to the latest one, or a version built on a latest version that is not active.", "properties": { "active_version_id": { "description": "Id of the version that was active when this one was created; only on `includes_unpublished_changes`.", "type": "string" }, "changed_fields_from_active": { "description": "Config paths that differ between the active version and the new one, named like `changed_fields`; only on `includes_unpublished_changes`.", "items": { "type": "string" }, "type": "array" }, "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one. `includes_unpublished_changes`: the new version was built on the latest version, which is not the active one, so it carries that version's unpublished changes.", "enum": ["mcp_tools_unverified", "no_changes", "includes_unpublished_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), that the new version is identical to the latest one (`no_changes`), or which fields differ from the active version and that they should be compared before activating (`includes_unpublished_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" }, { "type": "null" }], "description": "The version this call created; `null` when it did not create one." } }, "required": ["type", "id", "name", "description", "harness_type", "active_version_id", "created_at", "updated_at", "version"], "type": "object" } },
10
+ "agents.versions.create": { "body": { "additionalProperties": false, "properties": { "base_version_id": { "anyOf": [{ "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Id of the version you based this change on. If it is not the latest version, the call fails with 409 `base_version_mismatch` and `details.latest_version_id`. Send `null` to say the resource has no versions yet; omit it to skip the check." }, "change_message": { "description": "Note stored with the version.", "type": "string" }, "config": { "additionalProperties": false, "description": "Config to create an agent version. `model` is required; omitted keys use their defaults.", "properties": { "$schema": { "description": "JSON Schema URL for editors. Accepted and ignored; never stored.", "type": "string" }, "attachments": { "additionalProperties": false, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": false, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": false, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": false, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": false, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": false, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": false, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": false, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": false, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": false, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": false, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": false, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": false, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": false, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": false, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": false, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": false, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": false, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "pattern": "\\S", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": { "additionalProperties": false, "description": "A prompt block.", "properties": { "content": { "description": "Text of the block.", "type": "string" }, "type": { "const": "text", "description": "Block type. Only `text` is supported.", "type": "string" } }, "required": ["type", "content"], "type": "object" }, "type": "array" }, "reply": { "additionalProperties": false, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": false, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "type": "string" }, "name": { "description": "Name the model sees for the tool.", "type": "string" }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": { "additionalProperties": false, "description": "A header, body field, query parameter or path variable of an http tool.", "properties": { "accepted_values": { "description": "Values the model may choose from.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Tells the model what to put in this field.", "type": "string" }, "is_user_provided": { "description": "Whether the model fills this value on each call instead of a fixed one.", "type": "boolean" }, "key": { "description": "Name of the header, body field, query parameter or path variable.", "type": "string" }, "required": { "description": "Whether the model must provide this value.", "type": "boolean" }, "type": { "description": "Type of the value the model provides.", "type": "string" }, "value": { "description": "Fixed value sent on every call." } }, "required": ["key"], "type": "object" }, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call.", "type": "boolean" } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": false, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": false, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "required": ["model"], "type": "object" }, "mcp_connections": { "description": "MCP connections to assign. Each connection_id is the id of an MCP connection of the organization.", "items": { "additionalProperties": false, "description": "An MCP connection to assign to the agent.", "properties": { "connection_id": { "description": "Id of the MCP connection to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Names of the connection tools the agent can use; when omitted or empty, all of them. Use the `name` field of each tool the connection offers (not `agent_tool_name`). Validated at save: an unknown name is rejected and lists the valid ones.", "items": { "type": "string" }, "type": "array" }, "version_id": { "description": "Version of the connection to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["connection_id"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills to assign. Each skill_id is the id of a skill of the organization.", "items": { "additionalProperties": false, "description": "A skill to assign to the agent.", "properties": { "skill_id": { "description": "Id of the skill to assign.", "minLength": 1, "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "version_id": { "description": "Version of the skill to pin. Only with strategy `pin` (or no strategy); with `latest` the request fails with 400.", "minLength": 1, "type": "string" } }, "required": ["skill_id"], "type": "object" }, "type": "array" } }, "required": ["config"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`), a version identical to the latest one (`no_changes`) or a version that carries unpublished changes of a latest version that is not active (`includes_unpublished_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, a version identical to the latest one, or a version built on a latest version that is not active.", "properties": { "active_version_id": { "description": "Id of the version that was active when this one was created; only on `includes_unpublished_changes`.", "type": "string" }, "changed_fields_from_active": { "description": "Config paths that differ between the active version and the new one, named like `changed_fields`; only on `includes_unpublished_changes`.", "items": { "type": "string" }, "type": "array" }, "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one. `includes_unpublished_changes`: the new version was built on the latest version, which is not the active one, so it carries that version's unpublished changes.", "enum": ["mcp_tools_unverified", "no_changes", "includes_unpublished_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), that the new version is identical to the latest one (`no_changes`), or which fields differ from the active version and that they should be compared before activating (`includes_unpublished_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" } },
11
+ "agents.versions.restore": { "body": { "additionalProperties": false, "properties": { "activate": { "default": true, "description": "Whether to make the restored copy the active version. Defaults to true.", "type": "boolean" } }, "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent this version belongs to.", "type": "string" }, "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Config paths that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "config": { "additionalProperties": {}, "description": "Config of an agent version.", "properties": { "attachments": { "additionalProperties": {}, "description": "How the agent handles files sent by the user.", "properties": { "access": { "const": "inline", "default": "inline", "description": "How the model reads attachments. Only `inline` is supported.", "type": "string" }, "allow_reread": { "default": true, "description": "Whether the model can read an attachment again after the turn it arrived in.", "type": "boolean" }, "keep_in_history": { "default": false, "description": "Whether attachments stay in the history of later turns.", "type": "boolean" }, "max_tokens_per_attachment": { "default": 30000, "description": "Token limit for each attachment.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "max_tokens_per_message": { "default": 90000, "description": "Token limit for all the attachments of one message.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "type": "object" }, "follow_up": { "additionalProperties": {}, "description": "Writes to customers who stopped answering. Runs only on the WhatsApp, Instagram, Chatwoot and CRM channels.", "properties": { "decider": { "additionalProperties": {}, "description": "Filter that decides, before the agent runs, whether a follow-up makes sense.", "properties": { "enabled": { "default": false, "description": "Whether a filter reads the conversation before the agent and can stop the follow-up.", "type": "boolean" }, "model": { "default": "jev-1.14.0", "description": "Decision model of the filter. Its limits apply to the question: at most 255 options (10 categories plus `reasons`).", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "prompt": { "description": "Criteria of the filter: the instructions of its question. The platform adds the categories and `reasons` as the options to choose from. The default prompt when omitted.", "type": "string" }, "share_with_agent": { "default": true, "description": "Whether the filter result goes to the agent as a hint when it says to send.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": false, "description": "Whether the agent writes to customers who stopped answering. Channels: WhatsApp, Instagram, Chatwoot and CRM.", "type": "boolean" }, "instructions": { "description": "What every follow-up should do. Goes to the agent with each step.", "type": "string" }, "model": { "additionalProperties": {}, "description": "Model for the follow-up turns. The agent model when omitted.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "quiet_hours": { "additionalProperties": {}, "default": { "end": 6, "start": 0, "timezone": "America/Argentina/Cordoba" }, "description": "Hours when no follow-up goes out; a step that falls inside waits until they end.", "properties": { "end": { "description": "Hour when it ends (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "start": { "description": "Hour when the quiet period starts (0 to 23).", "maximum": 23, "minimum": 0, "type": "integer" }, "timezone": { "description": "IANA time zone, for example America/Argentina/Cordoba.", "type": "string" } }, "required": ["start", "end", "timezone"], "type": "object" }, "reasons": { "default": [], "description": "Reasons of your business; each one lives inside a fixed category.", "items": { "additionalProperties": {}, "description": "A reason of your business inside a fixed category.", "properties": { "category": { "description": "The fixed category this reason refines.", "enum": ["open_question", "cold_lead", "objection", "awaiting_confirmation", "other_send", "already_resolved", "not_interested", "asked_to_wait", "conversation_closed", "other_skip"], "type": "string" }, "description": { "description": "Tells the filter and the agent when to pick this reason. At most 500 characters.", "maxLength": 500, "type": "string" }, "id": { "description": "Id of the reason, unique in the list.", "type": "string" } }, "required": ["id", "category", "description"], "type": "object" }, "type": "array" }, "steps": { "default": [{ "delay_hours": 3 }], "description": "Steps in order: 1 to 3, and the delays must add up to less than 24 hours so every step goes out inside the 24-hour window.", "items": { "additionalProperties": {}, "description": "A step of the sequence.", "properties": { "delay_hours": { "description": "Hours to wait, at least 1. Step 1 counts from the last customer message; the next ones from the previous follow-up.", "type": "number" }, "instructions": { "description": "What this step adds to the general instructions.", "type": "string" } }, "required": ["delay_hours"], "type": "object" }, "type": "array" } }, "type": "object" }, "guardrails": { "additionalProperties": {}, "description": "Checks every incoming message before the agent runs. When a rule fires, the agent does not run and the customer gets that rule's reply. If the check itself fails, the agent runs normally.", "properties": { "default_reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of every rule that has no `reply` of its own." }, "rules": { "description": "Rules in order, at least one; the first one that fires answers. To turn the guardrail off, send `guardrails: null`.", "items": { "additionalProperties": {}, "description": "A rule: one question, a threshold and a reply.", "properties": { "model": { "default": "gemini-decision-1", "description": "Decision model that answers the question. Its limits apply to the question. The model also sees the attachments of the message that it reads: `gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG. Attachments the agent reads as text (documents, sheets) always go. Audio and video are not sent; audio arrives transcribed in the text. An attachment the model does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out.", "enum": ["gemini-decision-1", "jev-1.14.0"], "type": "string" }, "name": { "description": "Name of the rule: 1 to 64 characters (letters, digits, `_`, `-`), unique among the rules. `language` is reserved.", "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "phase": { "const": "input", "description": "When the rule runs. Only `input` is supported: before the agent reads the message.", "type": "string" }, "question": { "anyOf": [{ "additionalProperties": {}, "description": "Yes/no question.", "properties": { "criteria": { "additionalProperties": {}, "description": "Describes what each answer means.", "properties": { "false": { "description": "When the answer is no.", "type": "string" }, "true": { "description": "When the answer is yes.", "type": "string" } }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "boolean", "description": "A yes/no question.", "type": "string" } }, "required": ["type", "instructions"], "type": "object" }, { "additionalProperties": {}, "description": "Question with several options.", "properties": { "criteria": { "additionalProperties": { "type": "string" }, "description": "Options of the question: option name to its description.", "propertyNames": { "type": "string" }, "type": "object" }, "instructions": { "description": "The question the model answers about the message and its attachments (see `model`).", "type": "string" }, "type": { "const": "choice", "description": "A question with several options.", "type": "string" } }, "required": ["type", "instructions", "criteria"], "type": "object" }], "description": "What the model decides. Only `boolean` and `choice` are supported." }, "reply": { "anyOf": [{ "description": "One text for every language.", "type": "string" }, { "additionalProperties": { "description": "Text for that language.", "type": "string" }, "description": "One text per language code.", "propertyNames": { "type": "string" }, "type": "object" }], "description": "Reply of this rule. `default_reply` when omitted; one of the two is required." }, "trigger": { "additionalProperties": {}, "description": "When the rule fires.", "properties": { "choices": { "description": "Required for `choice`: the options that fire the rule. Each one must be in `question.criteria`.", "items": { "description": "An option of `question.criteria`.", "type": "string" }, "type": "array" }, "threshold": { "description": "Probability from 0 to 1. `boolean`: fires when the probability of yes reaches it. `choice`: fires when the probabilities of `choices` add up to it.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": ["threshold"], "type": "object" } }, "required": ["name", "phase", "question", "trigger"], "type": "object" }, "minItems": 1, "type": "array" } }, "required": ["rules"], "type": "object" }, "history": { "additionalProperties": {}, "description": "How much of the conversation is sent to the model on each turn.", "properties": { "exchanges": { "default": 12, "description": "How many previous user/agent exchanges are sent to the model (1 to 30).", "maximum": 30, "minimum": 1, "type": "integer" }, "reasoning": { "description": "Whether past reasoning is sent back to the model.", "type": "boolean" }, "tool_calls": { "anyOf": [{ "additionalProperties": {}, "description": "Tool calls are not kept in the history.", "properties": { "mode": { "const": "off", "description": "Tool calls are not kept.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Tool calls of every exchange in the history are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "all", "description": "Keep the tool calls of every exchange.", "type": "string" } }, "required": ["mode"], "type": "object" }, { "additionalProperties": {}, "description": "Only tool calls of the latest exchanges are kept.", "properties": { "exclude_tools": { "description": "Ids of tools whose calls are left out of the history.", "items": { "type": "string" }, "type": "array" }, "mode": { "const": "recent", "description": "Keep the tool calls of the latest exchanges only.", "type": "string" }, "turns": { "description": "How many of the latest exchanges keep their tool calls.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["mode", "turns"], "type": "object" }], "default": { "mode": "off" }, "description": "Which tool calls are kept in the history. Defaults to `off`." } }, "type": "object" }, "inbound": { "additionalProperties": {}, "description": "How the customer's messages come in. An empty object (`inbound: {}`) means queue without waiting: `debounce_ms` 0 and `queue_mode` `collect`.", "properties": { "debounce_ms": { "description": "Milliseconds to wait after the last customer message before running a turn with all of them (0 to 60000). 0 means no wait.", "maximum": 60000, "minimum": 0, "type": "integer" }, "queue_mode": { "const": "collect", "description": "What happens to a message that arrives while a turn is running. `collect`: it is added to the next turn. Only `collect` is supported.", "type": "string" } }, "type": "object" }, "knowledge": { "additionalProperties": {}, "description": "Knowledge the agent can search to answer.", "properties": { "mode": { "description": "How the knowledge is searched. Only `vector` is supported.", "enum": ["vector"], "type": "string" }, "project_ids": { "description": "Knowledge projects the agent can search. Each id is the id of a knowledge project of the organization.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "model": { "additionalProperties": {}, "description": "The model the agent runs on.", "properties": { "id": { "description": "Model id; one of the offered models.", "type": "string" }, "reasoning_effort": { "description": "How much the model reasons before answering; must be one of the reasoning levels of the chosen model. When omitted, the model default applies.", "enum": ["off", "low", "medium", "high", "max"], "type": "string" } }, "required": ["id"], "type": "object" }, "prompt": { "description": "System prompt, as a list of blocks that are joined in order.", "items": {}, "type": "array" }, "reply": { "additionalProperties": {}, "description": "How the agent's reply goes out.", "properties": { "split": { "default": "off", "description": "How the reply is split into bubbles. `off`: each channel's own default (Instagram still splits a long reply; each channel keeps its own pause between messages). `on`: bubbles, with pauses that depend on the channel, on every channel. `on_except_whatsapp`: bubbles everywhere except WhatsApp, where the reply goes out as one message. The channel is the real channel of the contact, not the transport: WhatsApp through Chatwoot or a CRM counts as WhatsApp. Defaults to `off`.", "enum": ["off", "on", "on_except_whatsapp"], "type": "string" } }, "type": "object" }, "tools": { "description": "Tools the model can call. Each non-http tool type at most once; thinking only when the model does not reason: a model that reasons cannot have it at any reasoning level, off included (see `capabilities.thinking_tool` in `models.list`). Saving it with such a model returns 400 `invalid_agent_config` with `details.reason` `thinking_tool_conflict`.", "items": { "anyOf": [{ "additionalProperties": {}, "description": "Calls an HTTP endpoint.", "properties": { "body": { "description": "Fields of the request body. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"city\", \"value\": \"Madrid\", \"description\": \"City to look up\" }]`.", "items": {}, "type": "array" }, "description": { "description": "Tells the model when to use the tool.", "type": "string" }, "headers": { "description": "Headers sent on every call. Each item is an object `{ key, value, description? }`, not a string; for example `[{ \"key\": \"Authorization\", \"value\": \"Bearer abc\" }]`.", "items": {}, "type": "array" }, "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "method": { "description": "HTTP method. Defaults to GET.", "type": "string" }, "name": { "description": "Name the model sees for the tool." }, "path_variables": { "description": "Values for the `{name}` placeholders of the url. Each item is an object `{ key, value, description? }` where `key` is the placeholder name; for example `[{ \"key\": \"id\", \"value\": \"123\", \"description\": \"Order id\" }]`.", "items": {}, "type": "array" }, "query_parameters": { "description": "Query parameters of the request. Each item is an object `{ key, value, description? }`; for example `[{ \"key\": \"page\", \"value\": \"1\" }]`.", "items": {}, "type": "array" }, "type": { "const": "http", "description": "Tool type: `http`.", "type": "string" }, "url": { "description": "URL the tool calls. Path variables are written as `{name}`.", "type": "string" }, "with_approval": { "description": "Whether a person must approve each call." } }, "required": ["type", "url"], "type": "object" }, { "additionalProperties": {}, "description": "Lets the model write down its reasoning before answering. Only for models that do not reason.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "instructions": { "description": "Extra instructions for how the model should think.", "type": "string" }, "max_thoughts": { "description": "Maximum number of thoughts per turn.", "type": "number" }, "type": { "const": "thinking", "description": "Tool type: `thinking`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model send files to the user.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "send_files", "description": "Tool type: `send_files`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }, { "additionalProperties": {}, "description": "Lets the model hand the conversation to a person.", "properties": { "id": { "description": "Assigned by the server when omitted; use it to edit or remove the tool. Must be unique among the tools.", "type": "string" }, "type": { "const": "request_human", "description": "Tool type: `request_human`.", "type": "string" } }, "required": ["type"], "type": "object", "x-single": true }] }, "type": "array" } }, "type": "object" }, "created_at": { "description": "When the version was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "created_by": { "description": "Id of the user or credential that created the version.", "type": "string" }, "harness_type": { "description": "Runtime the version runs on.", "enum": ["legacy", "mastra"], "type": "string" }, "id": { "description": "Id of the version.", "type": "string" }, "is_active": { "description": "Whether this is the version that is running.", "type": "boolean" }, "mcp_connections": { "description": "MCP connections assigned to this version.", "items": { "description": "An MCP connection assigned to the agent.", "properties": { "connection_id": { "description": "Id of the assigned MCP connection.", "type": "string" }, "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the connection in use when the strategy is `pin`; `null` otherwise." }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" }, "tools": { "description": "Server tool names of the connection the agent can use (the `name` field of each tool the connection offers); empty means all of them.", "items": { "type": "string" }, "type": "array" } }, "required": ["connection_id", "strategy", "pinned_version_id", "tools"], "type": "object" }, "type": "array" }, "skills": { "description": "Skills assigned to this version.", "items": { "description": "A skill assigned to the agent.", "properties": { "pinned_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Version of the skill in use when the strategy is `pin`; `null` otherwise." }, "skill_id": { "description": "Id of the assigned skill.", "type": "string" }, "strategy": { "description": "`pin` keeps a fixed version; `latest` follows the active version.", "enum": ["pin", "latest"], "type": "string" } }, "required": ["skill_id", "strategy", "pinned_version_id"], "type": "object" }, "type": "array" }, "type": { "const": "agent_version", "description": "Object type, always `agent_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Present only on the response of the call that created the version, and only when there is something to note: something saved without verification (`mcp_tools_unverified`), a version identical to the latest one (`no_changes`) or a version that carries unpublished changes of a latest version that is not active (`includes_unpublished_changes`).", "items": { "description": "A note about a version that was saved: something saved without being verified, a version identical to the latest one, or a version built on a latest version that is not active.", "properties": { "active_version_id": { "description": "Id of the version that was active when this one was created; only on `includes_unpublished_changes`.", "type": "string" }, "changed_fields_from_active": { "description": "Config paths that differ between the active version and the new one, named like `changed_fields`; only on `includes_unpublished_changes`.", "items": { "type": "string" }, "type": "array" }, "code": { "description": "`mcp_tools_unverified`: the MCP server could not be reached, so the tool names of this connection were saved without checking. `no_changes`: the new version is identical to the latest one. `includes_unpublished_changes`: the new version was built on the latest version, which is not the active one, so it carries that version's unpublished changes.", "enum": ["mcp_tools_unverified", "no_changes", "includes_unpublished_changes"], "type": "string" }, "connection_id": { "description": "Id of the MCP connection that could not be reached; only on `mcp_tools_unverified`.", "type": "string" }, "message": { "description": "What happened and what to do about it: what could not be checked and how to check it (`mcp_tools_unverified`), that the new version is identical to the latest one (`no_changes`), or which fields differ from the active version and that they should be compared before activating (`includes_unpublished_changes`).", "type": "string" } }, "required": ["code", "message"], "type": "object" }, "type": "array" } }, "required": ["type", "id", "agent_id", "version_number", "harness_type", "config", "skills", "mcp_connections", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" } },
12
12
  "agents.widgets.create": { "body": { "additionalProperties": false, "properties": { "allowed_domains": { "description": "Domains allowed to embed the widget (up to 50), like `example.com` or `*.example.com`. An empty list allows any site. An invalid one fails with `invalid_request`, `details.field` `allowed_domains[i]` and `details.reason`: `empty_domain`, `invalid_domain`, `localhost_not_supported` (use `127.0.0.1`), `wildcard_not_at_start`, `wildcard_too_broad` (a wildcard over a top-level domain or a whole public suffix like `*.com.ar`), `wildcard_on_ip` or `invalid_port`.", "items": { "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 50, "type": "array" }, "allows_anonymous": { "default": true, "description": "Whether visitors can chat without an identity token. In create, defaults to true.", "type": "boolean" }, "chat_widget": { "additionalProperties": false, "description": "Fields of `chat_widget` to set. In create, fields not sent take their default. In update, each field sent replaces that field whole (a nested object goes complete) and fields not sent stay as they are.", "properties": { "accent_color": { "additionalProperties": false, "description": "Accent color of the chat.", "properties": { "color": { "description": "Accent color, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "enabled": { "description": "Whether the accent color replaces the default one.", "type": "boolean" } }, "required": ["enabled", "color"], "type": "object" }, "agent_chat_bubble": { "description": "Whether the agent messages are shown inside a bubble.", "type": "boolean" }, "agent_picture_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "align_chat_button": { "description": "Corner of the screen where the chat button sits.", "enum": ["left", "right"], "type": "string" }, "auto_open_chat_window_after": { "anyOf": [{ "maximum": 600, "minimum": 0, "type": "integer" }, { "type": "null" }], "description": "Seconds after the page loads to show the initial messages as pop-ups next to the button (0 to 600); `null` turns it off." }, "button_color": { "anyOf": [{ "description": "Color of the chat button, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, { "type": "null" }], "description": "Color of the chat button, as a hex color like `#1f93ff`; `null` for the default color." }, "chat_bubble_text": { "additionalProperties": false, "description": "Text shown inside the chat button.", "properties": { "enabled": { "description": "Whether the text is shown.", "type": "boolean" }, "icon_alignment": { "description": "Side of the text where the icon goes.", "enum": ["left", "right"], "type": "string" }, "text": { "description": "Text next to the icon (1 to 30 characters).", "maxLength": 30, "minLength": 1, "type": "string" } }, "required": ["enabled", "text", "icon_alignment"], "type": "object" }, "chat_icon": { "description": "Icon of the chat button when no icon was uploaded.", "enum": ["laburen", "chats-filled", "chat-outline", "chats-outline"], "type": "string" }, "continue_showing_suggested_messages": { "description": "Whether the suggestions stay visible after each answer.", "type": "boolean" }, "dismissable_notice": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML notice above the message box that the visitor can close (up to 500 characters). Only bold, italic, underline, `https` links and paragraph alignment are kept; `null` hides it." }, "display_name": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Name shown in the header (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "footer": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML text below the message box (up to 500 characters), with the same rules as `dismissable_notice`; `null` hides it." }, "initial_messages": { "description": "Messages from the agent shown at the start of each conversation (up to 5, 1 to 500 characters each). They are not saved nor sent to the model.", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" }, "launcher_icon_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "mobile": { "additionalProperties": false, "description": "What changes on mobile (under 640 px).", "properties": { "auto_open_chat_window_after": { "anyOf": [{ "additionalProperties": false, "properties": { "enabled": { "description": "Whether mobile uses this delay.", "type": "boolean" }, "value": { "description": "Seconds for mobile (0 to 600).", "maximum": 600, "minimum": 0, "type": "integer" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Pop-up delay for mobile; `null` uses the desktop one." }, "initial_messages": { "anyOf": [{ "additionalProperties": false, "properties": { "enabled": { "description": "Whether mobile uses these messages.", "type": "boolean" }, "value": { "description": "Initial messages for mobile (up to 5).", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Initial messages for mobile; `null` uses the desktop ones." }, "show_auto_open": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the pop-ups show on mobile; `null` follows desktop." } }, "required": ["initial_messages", "auto_open_chat_window_after", "show_auto_open"], "type": "object" }, "radius": { "description": "Roundness of the corners.", "enum": ["sharp", "soft", "round", "pill"], "type": "string" }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_copy_button": { "description": "Whether the agent messages have a copy button.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "show_profile_picture_border": { "description": "Whether the agent picture has a border.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "additionalProperties": false, "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "additionalProperties": false, "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "tinted_grayscale": { "additionalProperties": false, "description": "Grays tinted with one hue.", "properties": { "enabled": { "description": "Whether the grays take the hue.", "type": "boolean" }, "hue": { "description": "Hue mixed into the grays (0 to 360).", "maximum": 360, "minimum": 0, "type": "integer" }, "shade": { "description": "How much hue goes into the dark grays (-4 to 4).", "maximum": 4, "minimum": -4, "type": "integer" }, "tint": { "description": "How much hue goes into the light grays (0 to 9).", "maximum": 9, "minimum": 0, "type": "integer" } }, "required": ["enabled", "hue", "tint", "shade"], "type": "object" }, "typography": { "additionalProperties": false, "description": "Font of the chat. Both fields are required.", "properties": { "font_family": { "description": "Font of the chat.", "enum": ["Inter", "System", "Arial", "Helvetica", "Georgia", "Geist"], "type": "string" }, "font_size": { "description": "Base font size.", "enum": ["12px", "14px", "16px", "18px", "20px"], "type": "string" } }, "required": ["font_family", "font_size"], "type": "object" }, "use_accent_for_header": { "description": "Whether the header is painted with the accent color.", "type": "boolean" }, "use_accent_for_send_icon": { "description": "Whether the send button is painted with the accent color.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": true, "description": "Whether the widget answers. In create, defaults to true.", "type": "boolean" }, "help_page": { "additionalProperties": false, "description": "Fields of `help_page` to set. In create, fields not sent take their default. In update, each field sent replaces that field whole (a nested object goes complete) and fields not sent stay as they are.", "properties": { "favicon_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "link_buttons": { "description": "More buttons with links in the sidebar (up to 5).", "items": { "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, "maxItems": 5, "type": "array" }, "logo_dark_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "logo_light_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "page_title": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Title of the browser tab (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "primary_button": { "anyOf": [{ "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Main button of the sidebar; `null` hides it." }, "primary_color": { "anyOf": [{ "additionalProperties": false, "properties": { "dark": { "description": "Main color in the dark theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "light": { "description": "Main color in the light theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" } }, "required": ["light", "dark"], "type": "object" }, { "type": "null" }], "description": "Main color of the page per theme; `null` for the default colors." }, "secondary_button": { "anyOf": [{ "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Second button of the sidebar; `null` hides it." }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "additionalProperties": false, "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "additionalProperties": false, "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "theme_switch_enabled": { "description": "Whether the visitor can switch between light and dark.", "type": "boolean" }, "top_message": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Welcome message above the message box (up to 200 characters); `null` for the default text." } }, "type": "object" }, "limit_reached_message": { "anyOf": [{ "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Text shown to a visitor who reached the cap (1 to 500 characters); `null` for the default text." }, "max_attachments_per_message": { "default": 5, "description": "Files a visitor can attach to one message (1 to 10). In create, defaults to 5.", "maximum": 10, "minimum": 1, "type": "integer" }, "name": { "description": "Name of the widget (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "visitor_rate_limit": { "anyOf": [{ "additionalProperties": false, "description": "Cap of messages per visitor.", "properties": { "interval_seconds": { "description": "Length of the interval, in seconds (1 to 2592000, 30 days).", "maximum": 2592000, "minimum": 1, "type": "integer" }, "max_messages": { "description": "Messages one visitor can send in the interval (1 to 100000).", "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": ["max_messages", "interval_seconds"], "type": "object" }, { "type": "null" }], "description": "Cap of messages per visitor; `null` removes the cap." } }, "required": ["name"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent that answers in the widget.", "type": "string" }, "allowed_domains": { "description": "Domains allowed to embed the widget; an empty list allows any site.", "items": { "type": "string" }, "type": "array" }, "allows_anonymous": { "description": "Whether visitors can chat without the site identifying them with an identity token.", "type": "boolean" }, "chat_widget": { "description": "Look and behavior of the chat bubble and the embedded chat.", "properties": { "accent_color": { "description": "Accent color of the chat.", "properties": { "color": { "description": "Accent color, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "enabled": { "description": "Whether the accent color replaces the default one.", "type": "boolean" } }, "required": ["enabled", "color"], "type": "object" }, "agent_chat_bubble": { "description": "Whether the agent messages are shown inside a bubble.", "type": "boolean" }, "agent_picture_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the agent picture; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "align_chat_button": { "description": "Corner of the screen where the chat button sits.", "enum": ["left", "right"], "type": "string" }, "auto_open_chat_window_after": { "anyOf": [{ "maximum": 600, "minimum": 0, "type": "integer" }, { "type": "null" }], "description": "Seconds after the page loads to show the initial messages as pop-ups next to the button (0 to 600); `null` turns it off." }, "button_color": { "anyOf": [{ "description": "Color of the chat button, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, { "type": "null" }], "description": "Color of the chat button, as a hex color like `#1f93ff`; `null` for the default color." }, "chat_bubble_text": { "description": "Text shown inside the chat button.", "properties": { "enabled": { "description": "Whether the text is shown.", "type": "boolean" }, "icon_alignment": { "description": "Side of the text where the icon goes.", "enum": ["left", "right"], "type": "string" }, "text": { "description": "Text next to the icon (1 to 30 characters).", "maxLength": 30, "minLength": 1, "type": "string" } }, "required": ["enabled", "text", "icon_alignment"], "type": "object" }, "chat_icon": { "description": "Icon of the chat button when no icon was uploaded.", "enum": ["laburen", "chats-filled", "chat-outline", "chats-outline"], "type": "string" }, "continue_showing_suggested_messages": { "description": "Whether the suggestions stay visible after each answer.", "type": "boolean" }, "dismissable_notice": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML notice above the message box that the visitor can close (up to 500 characters). Only bold, italic, underline, `https` links and paragraph alignment are kept; `null` hides it." }, "display_name": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Name shown in the header (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "footer": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML text below the message box (up to 500 characters), with the same rules as `dismissable_notice`; `null` hides it." }, "initial_messages": { "description": "Messages from the agent shown at the start of each conversation (up to 5, 1 to 500 characters each). They are not saved nor sent to the model.", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" }, "launcher_icon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the icon of the chat button; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "mobile": { "description": "What changes on mobile (under 640 px).", "properties": { "auto_open_chat_window_after": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses this delay.", "type": "boolean" }, "value": { "description": "Seconds for mobile (0 to 600).", "maximum": 600, "minimum": 0, "type": "integer" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Pop-up delay for mobile; `null` uses the desktop one." }, "initial_messages": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses these messages.", "type": "boolean" }, "value": { "description": "Initial messages for mobile (up to 5).", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Initial messages for mobile; `null` uses the desktop ones." }, "show_auto_open": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the pop-ups show on mobile; `null` follows desktop." } }, "required": ["initial_messages", "auto_open_chat_window_after", "show_auto_open"], "type": "object" }, "radius": { "description": "Roundness of the corners.", "enum": ["sharp", "soft", "round", "pill"], "type": "string" }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_copy_button": { "description": "Whether the agent messages have a copy button.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "show_profile_picture_border": { "description": "Whether the agent picture has a border.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "tinted_grayscale": { "description": "Grays tinted with one hue.", "properties": { "enabled": { "description": "Whether the grays take the hue.", "type": "boolean" }, "hue": { "description": "Hue mixed into the grays (0 to 360).", "maximum": 360, "minimum": 0, "type": "integer" }, "shade": { "description": "How much hue goes into the dark grays (-4 to 4).", "maximum": 4, "minimum": -4, "type": "integer" }, "tint": { "description": "How much hue goes into the light grays (0 to 9).", "maximum": 9, "minimum": 0, "type": "integer" } }, "required": ["enabled", "hue", "tint", "shade"], "type": "object" }, "typography": { "description": "Font of the chat. Both fields are required.", "properties": { "font_family": { "description": "Font of the chat.", "enum": ["Inter", "System", "Arial", "Helvetica", "Georgia", "Geist"], "type": "string" }, "font_size": { "description": "Base font size.", "enum": ["12px", "14px", "16px", "18px", "20px"], "type": "string" } }, "required": ["font_family", "font_size"], "type": "object" }, "use_accent_for_header": { "description": "Whether the header is painted with the accent color.", "type": "boolean" }, "use_accent_for_send_icon": { "description": "Whether the send button is painted with the accent color.", "type": "boolean" } }, "required": ["display_name", "initial_messages", "message_placeholder", "dismissable_notice", "footer", "suggested_messages", "continue_showing_suggested_messages", "auto_open_chat_window_after", "mobile", "show_attachments", "show_dictation", "show_copy_button", "agent_chat_bubble", "theme", "tinted_grayscale", "accent_color", "use_accent_for_header", "use_accent_for_send_icon", "radius", "typography", "show_profile_picture_border", "align_chat_button", "button_color", "chat_icon", "chat_bubble_text", "agent_picture_url", "launcher_icon_url"], "type": "object" }, "created_at": { "description": "When the widget was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "embed_iframe": { "description": "`<iframe>` that shows the chat inside a page, with `mode=embedded` and `allow=\"microphone\"`.", "type": "string" }, "enabled": { "description": "Whether the widget answers. A turned-off widget behaves as if it did not exist.", "type": "boolean" }, "help_page": { "description": "Look and behavior of the standalone help page.", "properties": { "favicon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the favicon of the page; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "link_buttons": { "description": "More buttons with links in the sidebar (up to 5).", "items": { "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, "maxItems": 5, "type": "array" }, "logo_dark_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the dark theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "logo_light_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the light theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "page_title": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Title of the browser tab (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "primary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Main button of the sidebar; `null` hides it." }, "primary_color": { "anyOf": [{ "properties": { "dark": { "description": "Main color in the dark theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "light": { "description": "Main color in the light theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" } }, "required": ["light", "dark"], "type": "object" }, { "type": "null" }], "description": "Main color of the page per theme; `null` for the default colors." }, "secondary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Second button of the sidebar; `null` hides it." }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "theme_switch_enabled": { "description": "Whether the visitor can switch between light and dark.", "type": "boolean" }, "top_message": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Welcome message above the message box (up to 200 characters); `null` for the default text." } }, "required": ["page_title", "top_message", "message_placeholder", "suggested_messages", "primary_button", "secondary_button", "link_buttons", "theme", "theme_switch_enabled", "primary_color", "show_dictation", "show_attachments", "favicon_url", "logo_light_url", "logo_dark_url"], "type": "object" }, "id": { "description": "Id of the widget.", "type": "string" }, "identity_secret": { "description": "Secret the site uses to sign identity tokens. Returned once: store it now, it cannot be read again.", "type": "string" }, "limit_reached_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Text shown to a visitor who reached the cap; `null` for the default text." }, "max_attachments_per_message": { "description": "Files a visitor can attach to one message.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "name": { "description": "Name of the widget.", "type": "string" }, "standalone_url": { "description": "URL of the standalone help page, with the token already set.", "type": "string" }, "token": { "description": "Public token of the widget; it goes in the snippet of the site.", "type": "string" }, "type": { "const": "widget", "description": "Object type, always `widget`.", "type": "string" }, "updated_at": { "description": "When the widget was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "visitor_rate_limit": { "anyOf": [{ "description": "Cap of messages per visitor.", "properties": { "interval_seconds": { "description": "Length of the interval, in seconds (1 to 2592000, 30 days).", "maximum": 2592000, "minimum": 1, "type": "integer" }, "max_messages": { "description": "Messages one visitor can send in the interval (1 to 100000).", "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": ["max_messages", "interval_seconds"], "type": "object" }, { "type": "null" }], "description": "Cap of messages per visitor; `null` when there is none." }, "web_widget_script": { "description": "Snippet of the chat bubble, ready to paste in the site: a `<script>` with the token and the base URL already set.", "type": "string" } }, "required": ["type", "id", "agent_id", "name", "token", "enabled", "allowed_domains", "allows_anonymous", "max_attachments_per_message", "visitor_rate_limit", "limit_reached_message", "chat_widget", "help_page", "web_widget_script", "embed_iframe", "standalone_url", "created_at", "updated_at", "identity_secret"], "type": "object" } },
13
13
  "agents.widgets.images.upload": { "body": { "properties": { "file": { "description": "The file, up to 1 MB (1048576 bytes).", "format": "binary", "type": "string" } }, "required": ["file"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent that answers in the widget.", "type": "string" }, "allowed_domains": { "description": "Domains allowed to embed the widget; an empty list allows any site.", "items": { "type": "string" }, "type": "array" }, "allows_anonymous": { "description": "Whether visitors can chat without the site identifying them with an identity token.", "type": "boolean" }, "chat_widget": { "description": "Look and behavior of the chat bubble and the embedded chat.", "properties": { "accent_color": { "description": "Accent color of the chat.", "properties": { "color": { "description": "Accent color, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "enabled": { "description": "Whether the accent color replaces the default one.", "type": "boolean" } }, "required": ["enabled", "color"], "type": "object" }, "agent_chat_bubble": { "description": "Whether the agent messages are shown inside a bubble.", "type": "boolean" }, "agent_picture_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the agent picture; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "align_chat_button": { "description": "Corner of the screen where the chat button sits.", "enum": ["left", "right"], "type": "string" }, "auto_open_chat_window_after": { "anyOf": [{ "maximum": 600, "minimum": 0, "type": "integer" }, { "type": "null" }], "description": "Seconds after the page loads to show the initial messages as pop-ups next to the button (0 to 600); `null` turns it off." }, "button_color": { "anyOf": [{ "description": "Color of the chat button, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, { "type": "null" }], "description": "Color of the chat button, as a hex color like `#1f93ff`; `null` for the default color." }, "chat_bubble_text": { "description": "Text shown inside the chat button.", "properties": { "enabled": { "description": "Whether the text is shown.", "type": "boolean" }, "icon_alignment": { "description": "Side of the text where the icon goes.", "enum": ["left", "right"], "type": "string" }, "text": { "description": "Text next to the icon (1 to 30 characters).", "maxLength": 30, "minLength": 1, "type": "string" } }, "required": ["enabled", "text", "icon_alignment"], "type": "object" }, "chat_icon": { "description": "Icon of the chat button when no icon was uploaded.", "enum": ["laburen", "chats-filled", "chat-outline", "chats-outline"], "type": "string" }, "continue_showing_suggested_messages": { "description": "Whether the suggestions stay visible after each answer.", "type": "boolean" }, "dismissable_notice": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML notice above the message box that the visitor can close (up to 500 characters). Only bold, italic, underline, `https` links and paragraph alignment are kept; `null` hides it." }, "display_name": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Name shown in the header (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "footer": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML text below the message box (up to 500 characters), with the same rules as `dismissable_notice`; `null` hides it." }, "initial_messages": { "description": "Messages from the agent shown at the start of each conversation (up to 5, 1 to 500 characters each). They are not saved nor sent to the model.", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" }, "launcher_icon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the icon of the chat button; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "mobile": { "description": "What changes on mobile (under 640 px).", "properties": { "auto_open_chat_window_after": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses this delay.", "type": "boolean" }, "value": { "description": "Seconds for mobile (0 to 600).", "maximum": 600, "minimum": 0, "type": "integer" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Pop-up delay for mobile; `null` uses the desktop one." }, "initial_messages": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses these messages.", "type": "boolean" }, "value": { "description": "Initial messages for mobile (up to 5).", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Initial messages for mobile; `null` uses the desktop ones." }, "show_auto_open": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the pop-ups show on mobile; `null` follows desktop." } }, "required": ["initial_messages", "auto_open_chat_window_after", "show_auto_open"], "type": "object" }, "radius": { "description": "Roundness of the corners.", "enum": ["sharp", "soft", "round", "pill"], "type": "string" }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_copy_button": { "description": "Whether the agent messages have a copy button.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "show_profile_picture_border": { "description": "Whether the agent picture has a border.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "tinted_grayscale": { "description": "Grays tinted with one hue.", "properties": { "enabled": { "description": "Whether the grays take the hue.", "type": "boolean" }, "hue": { "description": "Hue mixed into the grays (0 to 360).", "maximum": 360, "minimum": 0, "type": "integer" }, "shade": { "description": "How much hue goes into the dark grays (-4 to 4).", "maximum": 4, "minimum": -4, "type": "integer" }, "tint": { "description": "How much hue goes into the light grays (0 to 9).", "maximum": 9, "minimum": 0, "type": "integer" } }, "required": ["enabled", "hue", "tint", "shade"], "type": "object" }, "typography": { "description": "Font of the chat. Both fields are required.", "properties": { "font_family": { "description": "Font of the chat.", "enum": ["Inter", "System", "Arial", "Helvetica", "Georgia", "Geist"], "type": "string" }, "font_size": { "description": "Base font size.", "enum": ["12px", "14px", "16px", "18px", "20px"], "type": "string" } }, "required": ["font_family", "font_size"], "type": "object" }, "use_accent_for_header": { "description": "Whether the header is painted with the accent color.", "type": "boolean" }, "use_accent_for_send_icon": { "description": "Whether the send button is painted with the accent color.", "type": "boolean" } }, "required": ["display_name", "initial_messages", "message_placeholder", "dismissable_notice", "footer", "suggested_messages", "continue_showing_suggested_messages", "auto_open_chat_window_after", "mobile", "show_attachments", "show_dictation", "show_copy_button", "agent_chat_bubble", "theme", "tinted_grayscale", "accent_color", "use_accent_for_header", "use_accent_for_send_icon", "radius", "typography", "show_profile_picture_border", "align_chat_button", "button_color", "chat_icon", "chat_bubble_text", "agent_picture_url", "launcher_icon_url"], "type": "object" }, "created_at": { "description": "When the widget was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "embed_iframe": { "description": "`<iframe>` that shows the chat inside a page, with `mode=embedded` and `allow=\"microphone\"`.", "type": "string" }, "enabled": { "description": "Whether the widget answers. A turned-off widget behaves as if it did not exist.", "type": "boolean" }, "help_page": { "description": "Look and behavior of the standalone help page.", "properties": { "favicon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the favicon of the page; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "link_buttons": { "description": "More buttons with links in the sidebar (up to 5).", "items": { "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, "maxItems": 5, "type": "array" }, "logo_dark_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the dark theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "logo_light_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the light theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "page_title": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Title of the browser tab (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "primary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Main button of the sidebar; `null` hides it." }, "primary_color": { "anyOf": [{ "properties": { "dark": { "description": "Main color in the dark theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "light": { "description": "Main color in the light theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" } }, "required": ["light", "dark"], "type": "object" }, { "type": "null" }], "description": "Main color of the page per theme; `null` for the default colors." }, "secondary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Second button of the sidebar; `null` hides it." }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "theme_switch_enabled": { "description": "Whether the visitor can switch between light and dark.", "type": "boolean" }, "top_message": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Welcome message above the message box (up to 200 characters); `null` for the default text." } }, "required": ["page_title", "top_message", "message_placeholder", "suggested_messages", "primary_button", "secondary_button", "link_buttons", "theme", "theme_switch_enabled", "primary_color", "show_dictation", "show_attachments", "favicon_url", "logo_light_url", "logo_dark_url"], "type": "object" }, "id": { "description": "Id of the widget.", "type": "string" }, "limit_reached_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Text shown to a visitor who reached the cap; `null` for the default text." }, "max_attachments_per_message": { "description": "Files a visitor can attach to one message.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "name": { "description": "Name of the widget.", "type": "string" }, "standalone_url": { "description": "URL of the standalone help page, with the token already set.", "type": "string" }, "token": { "description": "Public token of the widget; it goes in the snippet of the site.", "type": "string" }, "type": { "const": "widget", "description": "Object type, always `widget`.", "type": "string" }, "updated_at": { "description": "When the widget was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "visitor_rate_limit": { "anyOf": [{ "description": "Cap of messages per visitor.", "properties": { "interval_seconds": { "description": "Length of the interval, in seconds (1 to 2592000, 30 days).", "maximum": 2592000, "minimum": 1, "type": "integer" }, "max_messages": { "description": "Messages one visitor can send in the interval (1 to 100000).", "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": ["max_messages", "interval_seconds"], "type": "object" }, { "type": "null" }], "description": "Cap of messages per visitor; `null` when there is none." }, "web_widget_script": { "description": "Snippet of the chat bubble, ready to paste in the site: a `<script>` with the token and the base URL already set.", "type": "string" } }, "required": ["type", "id", "agent_id", "name", "token", "enabled", "allowed_domains", "allows_anonymous", "max_attachments_per_message", "visitor_rate_limit", "limit_reached_message", "chat_widget", "help_page", "web_widget_script", "embed_iframe", "standalone_url", "created_at", "updated_at"], "type": "object" } },
14
14
  "agents.widgets.update": { "body": { "additionalProperties": false, "properties": { "allowed_domains": { "description": "Domains allowed to embed the widget (up to 50), like `example.com` or `*.example.com`. An empty list allows any site. An invalid one fails with `invalid_request`, `details.field` `allowed_domains[i]` and `details.reason`: `empty_domain`, `invalid_domain`, `localhost_not_supported` (use `127.0.0.1`), `wildcard_not_at_start`, `wildcard_too_broad` (a wildcard over a top-level domain or a whole public suffix like `*.com.ar`), `wildcard_on_ip` or `invalid_port`.", "items": { "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 50, "type": "array" }, "allows_anonymous": { "default": true, "description": "Whether visitors can chat without an identity token. In create, defaults to true.", "type": "boolean" }, "chat_widget": { "additionalProperties": false, "description": "Fields of `chat_widget` to set. In create, fields not sent take their default. In update, each field sent replaces that field whole (a nested object goes complete) and fields not sent stay as they are.", "properties": { "accent_color": { "additionalProperties": false, "description": "Accent color of the chat.", "properties": { "color": { "description": "Accent color, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "enabled": { "description": "Whether the accent color replaces the default one.", "type": "boolean" } }, "required": ["enabled", "color"], "type": "object" }, "agent_chat_bubble": { "description": "Whether the agent messages are shown inside a bubble.", "type": "boolean" }, "agent_picture_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "align_chat_button": { "description": "Corner of the screen where the chat button sits.", "enum": ["left", "right"], "type": "string" }, "auto_open_chat_window_after": { "anyOf": [{ "maximum": 600, "minimum": 0, "type": "integer" }, { "type": "null" }], "description": "Seconds after the page loads to show the initial messages as pop-ups next to the button (0 to 600); `null` turns it off." }, "button_color": { "anyOf": [{ "description": "Color of the chat button, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, { "type": "null" }], "description": "Color of the chat button, as a hex color like `#1f93ff`; `null` for the default color." }, "chat_bubble_text": { "additionalProperties": false, "description": "Text shown inside the chat button.", "properties": { "enabled": { "description": "Whether the text is shown.", "type": "boolean" }, "icon_alignment": { "description": "Side of the text where the icon goes.", "enum": ["left", "right"], "type": "string" }, "text": { "description": "Text next to the icon (1 to 30 characters).", "maxLength": 30, "minLength": 1, "type": "string" } }, "required": ["enabled", "text", "icon_alignment"], "type": "object" }, "chat_icon": { "description": "Icon of the chat button when no icon was uploaded.", "enum": ["laburen", "chats-filled", "chat-outline", "chats-outline"], "type": "string" }, "continue_showing_suggested_messages": { "description": "Whether the suggestions stay visible after each answer.", "type": "boolean" }, "dismissable_notice": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML notice above the message box that the visitor can close (up to 500 characters). Only bold, italic, underline, `https` links and paragraph alignment are kept; `null` hides it." }, "display_name": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Name shown in the header (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "footer": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML text below the message box (up to 500 characters), with the same rules as `dismissable_notice`; `null` hides it." }, "initial_messages": { "description": "Messages from the agent shown at the start of each conversation (up to 5, 1 to 500 characters each). They are not saved nor sent to the model.", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" }, "launcher_icon_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "mobile": { "additionalProperties": false, "description": "What changes on mobile (under 640 px).", "properties": { "auto_open_chat_window_after": { "anyOf": [{ "additionalProperties": false, "properties": { "enabled": { "description": "Whether mobile uses this delay.", "type": "boolean" }, "value": { "description": "Seconds for mobile (0 to 600).", "maximum": 600, "minimum": 0, "type": "integer" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Pop-up delay for mobile; `null` uses the desktop one." }, "initial_messages": { "anyOf": [{ "additionalProperties": false, "properties": { "enabled": { "description": "Whether mobile uses these messages.", "type": "boolean" }, "value": { "description": "Initial messages for mobile (up to 5).", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Initial messages for mobile; `null` uses the desktop ones." }, "show_auto_open": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the pop-ups show on mobile; `null` follows desktop." } }, "required": ["initial_messages", "auto_open_chat_window_after", "show_auto_open"], "type": "object" }, "radius": { "description": "Roundness of the corners.", "enum": ["sharp", "soft", "round", "pill"], "type": "string" }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_copy_button": { "description": "Whether the agent messages have a copy button.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "show_profile_picture_border": { "description": "Whether the agent picture has a border.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "additionalProperties": false, "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "additionalProperties": false, "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "tinted_grayscale": { "additionalProperties": false, "description": "Grays tinted with one hue.", "properties": { "enabled": { "description": "Whether the grays take the hue.", "type": "boolean" }, "hue": { "description": "Hue mixed into the grays (0 to 360).", "maximum": 360, "minimum": 0, "type": "integer" }, "shade": { "description": "How much hue goes into the dark grays (-4 to 4).", "maximum": 4, "minimum": -4, "type": "integer" }, "tint": { "description": "How much hue goes into the light grays (0 to 9).", "maximum": 9, "minimum": 0, "type": "integer" } }, "required": ["enabled", "hue", "tint", "shade"], "type": "object" }, "typography": { "additionalProperties": false, "description": "Font of the chat. Both fields are required.", "properties": { "font_family": { "description": "Font of the chat.", "enum": ["Inter", "System", "Arial", "Helvetica", "Georgia", "Geist"], "type": "string" }, "font_size": { "description": "Base font size.", "enum": ["12px", "14px", "16px", "18px", "20px"], "type": "string" } }, "required": ["font_family", "font_size"], "type": "object" }, "use_accent_for_header": { "description": "Whether the header is painted with the accent color.", "type": "boolean" }, "use_accent_for_send_icon": { "description": "Whether the send button is painted with the accent color.", "type": "boolean" } }, "type": "object" }, "enabled": { "default": true, "description": "Whether the widget answers. In create, defaults to true.", "type": "boolean" }, "help_page": { "additionalProperties": false, "description": "Fields of `help_page` to set. In create, fields not sent take their default. In update, each field sent replaces that field whole (a nested object goes complete) and fields not sent stay as they are.", "properties": { "favicon_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "link_buttons": { "description": "More buttons with links in the sidebar (up to 5).", "items": { "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, "maxItems": 5, "type": "array" }, "logo_dark_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "logo_light_url": { "description": "Read-only: it comes in the response and cannot be sent.", "not": {} }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "page_title": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Title of the browser tab (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "primary_button": { "anyOf": [{ "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Main button of the sidebar; `null` hides it." }, "primary_color": { "anyOf": [{ "additionalProperties": false, "properties": { "dark": { "description": "Main color in the dark theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "light": { "description": "Main color in the light theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" } }, "required": ["light", "dark"], "type": "object" }, { "type": "null" }], "description": "Main color of the page per theme; `null` for the default colors." }, "secondary_button": { "anyOf": [{ "additionalProperties": false, "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Second button of the sidebar; `null` hides it." }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "additionalProperties": false, "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "additionalProperties": false, "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "theme_switch_enabled": { "description": "Whether the visitor can switch between light and dark.", "type": "boolean" }, "top_message": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Welcome message above the message box (up to 200 characters); `null` for the default text." } }, "type": "object" }, "limit_reached_message": { "anyOf": [{ "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" }], "description": "Text shown to a visitor who reached the cap (1 to 500 characters); `null` for the default text." }, "max_attachments_per_message": { "default": 5, "description": "Files a visitor can attach to one message (1 to 10). In create, defaults to 5.", "maximum": 10, "minimum": 1, "type": "integer" }, "name": { "description": "Name of the widget (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "visitor_rate_limit": { "anyOf": [{ "additionalProperties": false, "description": "Cap of messages per visitor.", "properties": { "interval_seconds": { "description": "Length of the interval, in seconds (1 to 2592000, 30 days).", "maximum": 2592000, "minimum": 1, "type": "integer" }, "max_messages": { "description": "Messages one visitor can send in the interval (1 to 100000).", "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": ["max_messages", "interval_seconds"], "type": "object" }, { "type": "null" }], "description": "Cap of messages per visitor; `null` removes the cap." } }, "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent that answers in the widget.", "type": "string" }, "allowed_domains": { "description": "Domains allowed to embed the widget; an empty list allows any site.", "items": { "type": "string" }, "type": "array" }, "allows_anonymous": { "description": "Whether visitors can chat without the site identifying them with an identity token.", "type": "boolean" }, "chat_widget": { "description": "Look and behavior of the chat bubble and the embedded chat.", "properties": { "accent_color": { "description": "Accent color of the chat.", "properties": { "color": { "description": "Accent color, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "enabled": { "description": "Whether the accent color replaces the default one.", "type": "boolean" } }, "required": ["enabled", "color"], "type": "object" }, "agent_chat_bubble": { "description": "Whether the agent messages are shown inside a bubble.", "type": "boolean" }, "agent_picture_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the agent picture; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "align_chat_button": { "description": "Corner of the screen where the chat button sits.", "enum": ["left", "right"], "type": "string" }, "auto_open_chat_window_after": { "anyOf": [{ "maximum": 600, "minimum": 0, "type": "integer" }, { "type": "null" }], "description": "Seconds after the page loads to show the initial messages as pop-ups next to the button (0 to 600); `null` turns it off." }, "button_color": { "anyOf": [{ "description": "Color of the chat button, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, { "type": "null" }], "description": "Color of the chat button, as a hex color like `#1f93ff`; `null` for the default color." }, "chat_bubble_text": { "description": "Text shown inside the chat button.", "properties": { "enabled": { "description": "Whether the text is shown.", "type": "boolean" }, "icon_alignment": { "description": "Side of the text where the icon goes.", "enum": ["left", "right"], "type": "string" }, "text": { "description": "Text next to the icon (1 to 30 characters).", "maxLength": 30, "minLength": 1, "type": "string" } }, "required": ["enabled", "text", "icon_alignment"], "type": "object" }, "chat_icon": { "description": "Icon of the chat button when no icon was uploaded.", "enum": ["laburen", "chats-filled", "chat-outline", "chats-outline"], "type": "string" }, "continue_showing_suggested_messages": { "description": "Whether the suggestions stay visible after each answer.", "type": "boolean" }, "dismissable_notice": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML notice above the message box that the visitor can close (up to 500 characters). Only bold, italic, underline, `https` links and paragraph alignment are kept; `null` hides it." }, "display_name": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Name shown in the header (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "footer": { "anyOf": [{ "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "HTML text below the message box (up to 500 characters), with the same rules as `dismissable_notice`; `null` hides it." }, "initial_messages": { "description": "Messages from the agent shown at the start of each conversation (up to 5, 1 to 500 characters each). They are not saved nor sent to the model.", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" }, "launcher_icon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the icon of the chat button; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "mobile": { "description": "What changes on mobile (under 640 px).", "properties": { "auto_open_chat_window_after": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses this delay.", "type": "boolean" }, "value": { "description": "Seconds for mobile (0 to 600).", "maximum": 600, "minimum": 0, "type": "integer" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Pop-up delay for mobile; `null` uses the desktop one." }, "initial_messages": { "anyOf": [{ "properties": { "enabled": { "description": "Whether mobile uses these messages.", "type": "boolean" }, "value": { "description": "Initial messages for mobile (up to 5).", "items": { "maxLength": 500, "minLength": 1, "type": "string" }, "maxItems": 5, "type": "array" } }, "required": ["enabled", "value"], "type": "object" }, { "type": "null" }], "description": "Initial messages for mobile; `null` uses the desktop ones." }, "show_auto_open": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the pop-ups show on mobile; `null` follows desktop." } }, "required": ["initial_messages", "auto_open_chat_window_after", "show_auto_open"], "type": "object" }, "radius": { "description": "Roundness of the corners.", "enum": ["sharp", "soft", "round", "pill"], "type": "string" }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_copy_button": { "description": "Whether the agent messages have a copy button.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "show_profile_picture_border": { "description": "Whether the agent picture has a border.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "tinted_grayscale": { "description": "Grays tinted with one hue.", "properties": { "enabled": { "description": "Whether the grays take the hue.", "type": "boolean" }, "hue": { "description": "Hue mixed into the grays (0 to 360).", "maximum": 360, "minimum": 0, "type": "integer" }, "shade": { "description": "How much hue goes into the dark grays (-4 to 4).", "maximum": 4, "minimum": -4, "type": "integer" }, "tint": { "description": "How much hue goes into the light grays (0 to 9).", "maximum": 9, "minimum": 0, "type": "integer" } }, "required": ["enabled", "hue", "tint", "shade"], "type": "object" }, "typography": { "description": "Font of the chat. Both fields are required.", "properties": { "font_family": { "description": "Font of the chat.", "enum": ["Inter", "System", "Arial", "Helvetica", "Georgia", "Geist"], "type": "string" }, "font_size": { "description": "Base font size.", "enum": ["12px", "14px", "16px", "18px", "20px"], "type": "string" } }, "required": ["font_family", "font_size"], "type": "object" }, "use_accent_for_header": { "description": "Whether the header is painted with the accent color.", "type": "boolean" }, "use_accent_for_send_icon": { "description": "Whether the send button is painted with the accent color.", "type": "boolean" } }, "required": ["display_name", "initial_messages", "message_placeholder", "dismissable_notice", "footer", "suggested_messages", "continue_showing_suggested_messages", "auto_open_chat_window_after", "mobile", "show_attachments", "show_dictation", "show_copy_button", "agent_chat_bubble", "theme", "tinted_grayscale", "accent_color", "use_accent_for_header", "use_accent_for_send_icon", "radius", "typography", "show_profile_picture_border", "align_chat_button", "button_color", "chat_icon", "chat_bubble_text", "agent_picture_url", "launcher_icon_url"], "type": "object" }, "created_at": { "description": "When the widget was created (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "embed_iframe": { "description": "`<iframe>` that shows the chat inside a page, with `mode=embedded` and `allow=\"microphone\"`.", "type": "string" }, "enabled": { "description": "Whether the widget answers. A turned-off widget behaves as if it did not exist.", "type": "boolean" }, "help_page": { "description": "Look and behavior of the standalone help page.", "properties": { "favicon_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the favicon of the page; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "link_buttons": { "description": "More buttons with links in the sidebar (up to 5).", "items": { "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, "maxItems": 5, "type": "array" }, "logo_dark_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the dark theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "logo_light_url": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "URL of the logo for the light theme; `null` when none was uploaded. Read-only: it is set by uploading the image." }, "message_placeholder": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Placeholder of the message box (up to 200 characters); `null` for the default text." }, "page_title": { "anyOf": [{ "maxLength": 100, "minLength": 1, "pattern": "\\S", "type": "string" }, { "type": "null" }], "description": "Title of the browser tab (1 to 100 characters, not only spaces); `null` uses the name of the widget." }, "primary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Main button of the sidebar; `null` hides it." }, "primary_color": { "anyOf": [{ "properties": { "dark": { "description": "Main color in the dark theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "light": { "description": "Main color in the light theme, as a hex color like `#1f93ff`.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" } }, "required": ["light", "dark"], "type": "object" }, { "type": "null" }], "description": "Main color of the page per theme; `null` for the default colors." }, "secondary_button": { "anyOf": [{ "description": "A button with a link.", "properties": { "link": { "description": "`https` URL the button opens.", "format": "uri", "maxLength": 2048, "type": "string" }, "text": { "description": "Text of the button (1 to 50 characters).", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": ["text", "link"], "type": "object" }, { "type": "null" }], "description": "Second button of the sidebar; `null` hides it." }, "show_attachments": { "description": "Whether the visitor can attach files.", "type": "boolean" }, "show_dictation": { "description": "Whether the microphone button for dictation is shown.", "type": "boolean" }, "suggested_messages": { "description": "Quick replies shown when the conversation is empty (up to 20).", "items": { "anyOf": [{ "description": "A suggestion that sends its text.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "const": "single", "description": "A button that sends its text.", "type": "string" } }, "required": ["type", "text", "order", "icon"], "type": "object" }, { "description": "A group of suggestions.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "items": { "description": "Suggestions of the group (1 to 20).", "items": { "description": "A suggestion inside the group.", "properties": { "icon": { "anyOf": [{ "enum": ["message-circle", "circle-help", "info", "shopping-cart", "calendar", "phone", "mail", "tag", "truck", "credit-card", "user", "star"], "type": "string" }, { "type": "null" }], "description": "Icon shown next to the text; `null` for none." }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "text": { "description": "Text shown and sent when clicked (1 to 200 characters).", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["text", "order", "icon"], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "name": { "description": "Name of the group (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "order": { "description": "Position in the list, from 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "type": { "const": "nested", "description": "A button that opens a group of suggestions.", "type": "string" } }, "required": ["type", "name", "order", "icon", "items"], "type": "object" }] }, "maxItems": 20, "type": "array" }, "theme": { "description": "Color theme; `auto` follows the visitor system.", "enum": ["light", "dark", "auto"], "type": "string" }, "theme_switch_enabled": { "description": "Whether the visitor can switch between light and dark.", "type": "boolean" }, "top_message": { "anyOf": [{ "maxLength": 200, "type": "string" }, { "type": "null" }], "description": "Welcome message above the message box (up to 200 characters); `null` for the default text." } }, "required": ["page_title", "top_message", "message_placeholder", "suggested_messages", "primary_button", "secondary_button", "link_buttons", "theme", "theme_switch_enabled", "primary_color", "show_dictation", "show_attachments", "favicon_url", "logo_light_url", "logo_dark_url"], "type": "object" }, "id": { "description": "Id of the widget.", "type": "string" }, "limit_reached_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Text shown to a visitor who reached the cap; `null` for the default text." }, "max_attachments_per_message": { "description": "Files a visitor can attach to one message.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "name": { "description": "Name of the widget.", "type": "string" }, "standalone_url": { "description": "URL of the standalone help page, with the token already set.", "type": "string" }, "token": { "description": "Public token of the widget; it goes in the snippet of the site.", "type": "string" }, "type": { "const": "widget", "description": "Object type, always `widget`.", "type": "string" }, "updated_at": { "description": "When the widget was last changed (RFC 3339).", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "visitor_rate_limit": { "anyOf": [{ "description": "Cap of messages per visitor.", "properties": { "interval_seconds": { "description": "Length of the interval, in seconds (1 to 2592000, 30 days).", "maximum": 2592000, "minimum": 1, "type": "integer" }, "max_messages": { "description": "Messages one visitor can send in the interval (1 to 100000).", "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": ["max_messages", "interval_seconds"], "type": "object" }, { "type": "null" }], "description": "Cap of messages per visitor; `null` when there is none." }, "web_widget_script": { "description": "Snippet of the chat bubble, ready to paste in the site: a `<script>` with the token and the base URL already set.", "type": "string" } }, "required": ["type", "id", "agent_id", "name", "token", "enabled", "allowed_domains", "allows_anonymous", "max_attachments_per_message", "visitor_rate_limit", "limit_reached_message", "chat_widget", "help_page", "web_widget_script", "embed_iframe", "standalone_url", "created_at", "updated_at"], "type": "object" } },