@laburen/delta-cli 0.2.0-canary.20 → 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.
- package/dist/commands/agent-checks.js +10 -3
- package/dist/commands/agent-checks.js.map +1 -1
- package/dist/commands/agent-run/body.d.ts +4 -2
- package/dist/commands/agent-run/body.js +11 -7
- package/dist/commands/agent-run/body.js.map +1 -1
- package/dist/commands/agent-run.d.ts +27 -0
- package/dist/commands/agent-run.js +11 -10
- package/dist/commands/agent-run.js.map +1 -1
- package/dist/commands/agent-send-message.d.ts +10 -0
- package/dist/commands/agent-send-message.js +134 -0
- package/dist/commands/agent-send-message.js.map +1 -0
- package/dist/commands/agent-tools/add.js +2 -1
- package/dist/commands/agent-tools/add.js.map +1 -1
- package/dist/commands/agent-tools/remove.js +2 -1
- package/dist/commands/agent-tools/remove.js.map +1 -1
- package/dist/commands/agent-tools/shared.d.ts +38 -14
- package/dist/commands/agent-tools/shared.js +17 -0
- package/dist/commands/agent-tools/shared.js.map +1 -1
- package/dist/errors.js +29 -12
- package/dist/errors.js.map +1 -1
- package/dist/generated/commands.js +3 -3
- package/dist/generated/commands.js.map +1 -1
- package/dist/generated/schemas.d.ts +8 -0
- package/dist/generated/schemas.js +19 -6
- package/dist/generated/schemas.js.map +1 -1
- package/dist/operations/schema-flag.d.ts +1 -0
- package/dist/operations/schema-flag.js +5 -2
- package/dist/operations/schema-flag.js.map +1 -1
- package/dist/program.js +2 -0
- package/dist/program.js.map +1 -1
- package/docs/SKILL.md +5 -4
- package/docs/references/commands.md +62 -9
- package/docs/references/output-and-errors.md +9 -5
- package/package.json +2 -2
|
@@ -1,13 +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": { "additionalProperties": false, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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": { "additionalProperties": {}, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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
|
-
"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 none." }, "confidence": { "description": "Confidence of the filter, from 0 to 1.", "type": "number" }, "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" }, "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" }, "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" }, "reason": { "description": "Why the filter decided it, in one or two sentences.", "type": "string" }, "reasoning": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Reasoning of the model, when the provider returns it; `null` otherwise." } }, "required": ["decision", "category", "child_reason", "reason", "confidence", "reasoning", "model", "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`)." }, "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" } },
|
|
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
|
+
"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" } },
|
|
7
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 },
|
|
8
|
-
"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": { "additionalProperties": false, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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." }, "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." }, "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": { "additionalProperties": {}, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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" } },
|
|
9
|
-
"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": { "additionalProperties": false, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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": { "additionalProperties": {}, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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" } },
|
|
10
|
-
"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": { "additionalProperties": {}, "default": { "id": "gpt_5_mini_openrouter" }, "description": "Model of the filter.", "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": "Criteria of the filter. The platform appends the categories and the output format. 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" }, "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" }, "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" } },
|
|
11
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" } },
|
|
12
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" } },
|
|
13
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" } },
|
|
@@ -19,10 +20,22 @@ export const OPERATION_SCHEMAS = {
|
|
|
19
20
|
"skills.create": { "body": { "additionalProperties": false, "properties": { "activate": { "description": "Whether to make the first version the active one. Defaults to true.", "type": "boolean" }, "change_message": { "description": "Note stored with the first version.", "type": "string" }, "files": { "additionalProperties": { "type": "string" }, "description": "Files of the skill: path to content. `SKILL.md` is required.", "propertyNames": { "type": "string" }, "type": "object" }, "name": { "description": "Name of the skill.", "minLength": 1, "type": "string" } }, "required": ["name", "files"], "type": "object" }, "response": { "properties": { "active_version_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the version in use; `null` when none is active." }, "created_at": { "description": "When the skill 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 skill.", "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Description from the SKILL.md of the active version, or of the latest version when none is active; `null` when the skill has no versions." }, "id": { "description": "Id of the skill.", "type": "string" }, "name": { "description": "Name of the skill.", "type": "string" }, "status": { "description": "`draft` until a version is activated; `published` afterwards.", "enum": ["draft", "published"], "type": "string" }, "type": { "const": "skill", "description": "Object type, always `skill`.", "type": "string" }, "updated_at": { "description": "When the skill 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": { "properties": { "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Fields that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "compatibility": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Compatibility notes declared in SKILL.md; `null` when there are none." }, "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" }, "description": { "description": "What the skill does and when to use it, from SKILL.md.", "type": "string" }, "files": { "description": "Paths of the files of the version, not counting SKILL.md.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Id of the version.", "type": "string" }, "instructions": { "description": "Body of SKILL.md: the instructions the model follows.", "type": "string" }, "is_active": { "description": "Whether this is the version in use.", "type": "boolean" }, "license": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "License declared in SKILL.md; `null` when there is none." }, "metadata": { "description": "Free-form metadata declared in SKILL.md; returned as it was written." }, "name": { "description": "Name of the skill, from SKILL.md.", "type": "string" }, "skill_id": { "description": "Id of the skill this version belongs to.", "type": "string" }, "type": { "const": "skill_version", "description": "Object type, always `skill_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": ["type", "id", "skill_id", "version_number", "name", "description", "instructions", "license", "compatibility", "metadata", "files", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" }, "warnings": { "description": "Notes that did not stop the save: problems found while reading SKILL.md, or that the new version is identical to the latest one.", "items": { "type": "string" }, "type": "array" } }, "required": ["type", "id", "name", "status", "active_version_id", "description", "created_by", "created_at", "updated_at", "version", "warnings"], "type": "object" } },
|
|
20
21
|
"skills.versions.create": { "body": { "additionalProperties": false, "properties": { "change_message": { "description": "Note stored with the version.", "type": "string" }, "files": { "additionalProperties": { "type": "string" }, "description": "Files of the skill: path to content. `SKILL.md` is required.", "propertyNames": { "type": "string" }, "type": "object" } }, "required": ["files"], "type": "object" }, "response": { "properties": { "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Fields that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "compatibility": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Compatibility notes declared in SKILL.md; `null` when there are none." }, "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" }, "description": { "description": "What the skill does and when to use it, from SKILL.md.", "type": "string" }, "files": { "description": "Paths of the files of the version, not counting SKILL.md.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Id of the version.", "type": "string" }, "instructions": { "description": "Body of SKILL.md: the instructions the model follows.", "type": "string" }, "is_active": { "description": "Whether this is the version in use.", "type": "boolean" }, "license": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "License declared in SKILL.md; `null` when there is none." }, "metadata": { "description": "Free-form metadata declared in SKILL.md; returned as it was written." }, "name": { "description": "Name of the skill, from SKILL.md.", "type": "string" }, "skill_id": { "description": "Id of the skill this version belongs to.", "type": "string" }, "type": { "const": "skill_version", "description": "Object type, always `skill_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "warnings": { "description": "Notes that did not stop the save: problems found while reading SKILL.md, or that the new version is identical to the latest one.", "items": { "type": "string" }, "type": "array" } }, "required": ["type", "id", "skill_id", "version_number", "name", "description", "instructions", "license", "compatibility", "metadata", "files", "changed_fields", "change_message", "created_by", "created_at", "is_active", "warnings"], "type": "object" } },
|
|
21
22
|
"skills.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": { "change_message": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Note written when the version was created; `null` when there is none." }, "changed_fields": { "description": "Fields that changed compared with the previous version.", "items": { "type": "string" }, "type": "array" }, "compatibility": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Compatibility notes declared in SKILL.md; `null` when there are none." }, "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" }, "description": { "description": "What the skill does and when to use it, from SKILL.md.", "type": "string" }, "files": { "description": "Paths of the files of the version, not counting SKILL.md.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Id of the version.", "type": "string" }, "instructions": { "description": "Body of SKILL.md: the instructions the model follows.", "type": "string" }, "is_active": { "description": "Whether this is the version in use.", "type": "boolean" }, "license": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "License declared in SKILL.md; `null` when there is none." }, "metadata": { "description": "Free-form metadata declared in SKILL.md; returned as it was written." }, "name": { "description": "Name of the skill, from SKILL.md.", "type": "string" }, "skill_id": { "description": "Id of the skill this version belongs to.", "type": "string" }, "type": { "const": "skill_version", "description": "Object type, always `skill_version`.", "type": "string" }, "version_number": { "description": "Sequential number of the version, starting at 1.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": ["type", "id", "skill_id", "version_number", "name", "description", "instructions", "license", "compatibility", "metadata", "files", "changed_fields", "change_message", "created_by", "created_at", "is_active"], "type": "object" } },
|
|
22
|
-
"threads.create": { "body": { "additionalProperties": false, "properties": { "agent_id": { "description": "Id of the agent that will answer in this thread. It cannot be an agent in conversational mode.", "minLength": 1, "type": "string" }, "channel": { "anyOf": [{ "additionalProperties": false, "description": "Link the thread to a WhatsApp conversation, so replies and follow-ups reach the customer. The conversation is created if it does not exist.", "properties": { "phone_number_id": { "description": "Id of the WhatsApp number (`phone_number_id` of Meta) that sent the template. It must be a WhatsApp number of your organization connected to this same agent.", "minLength": 1, "type": "string" }, "to": { "description": "Identifier of the customer that Meta returned when the template was sent: `contacts[0].wa_id` (digits only, no `+` or spaces) or `contacts[0].user_id` (a BSUID such as `AR.123456`). If Meta returns both, send the `wa_id`. Anything else is rejected.", "type": "string" }, "type": { "const": "whatsapp", "description": "Channel type, always `whatsapp`.", "type": "string" } }, "required": ["type", "phone_number_id", "to"], "type": "object" }, { "additionalProperties": false, "description": "Link the thread to a conversation of the CRM connected to the agent.", "properties": { "account_id": { "description": "Id of the account in the CRM that owns the conversation.", "minLength": 1, "type": "string" }, "conversation_id": { "description": "Id of the conversation in the CRM, as the CRM reports it. It is not the id of the contact nor one you make up: the template must have been sent through the CRM so that the conversation exists.", "minLength": 1, "type": "string" }, "type": { "const": "crm", "description": "Channel type, always `crm`.", "type": "string" } }, "required": ["type", "account_id", "conversation_id"], "type": "object" }, { "additionalProperties": false, "description": "Link the thread to a Chatwoot conversation of the agent.", "properties": { "conversation_id": { "description": "Id of the conversation in Chatwoot, as Chatwoot reports it. It is not the id of the contact nor one you make up: the template must have been sent through Chatwoot so that the conversation exists.", "minLength": 1, "type": "string" }, "type": { "const": "chatwoot", "description": "Channel type, always `chatwoot`.", "type": "string" } }, "required": ["type", "conversation_id"], "type": "object" }], "description": "The channel conversation the thread must be linked to. The channel type is the `type` field; each type accepts only its own fields." }, "contact": { "additionalProperties": false, "description": "Profile of the end user, used only when `resource` creates a new contact. Fields that clash with another contact are left out, without warning.", "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" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "Creates an evals thread: runs on it must send the same `environment`, as in an agent run. Omit it, or send `null`, for production. It cannot go with `channel`, because a channel conversation is a real one: it returns 400 `invalid_request` with `details.reason` `channel_conversation_is_real`." }, "messages": { "description": "Messages to store when the thread is created, in the order you send them, with no limit on the number of messages, but the whole request body is capped at about 1 MB (a bigger one gets 413): send long histories in several calls. Storing messages does not run the agent: run it on this thread afterwards (send `memory.thread` in an agent run, or use `laburen agents run --thread`).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A message of the end user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. A message needs some text or at least one file.", "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` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, { "additionalProperties": false, "description": "A message of the agent.", "properties": { "parts": { "description": "Content of the message: text parts only. File parts are rejected in an `assistant` message.", "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": { "const": "assistant", "description": "Author of the message, always `assistant` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }], "description": "A message to store in the thread. `role` is `user` or `assistant`; `system` is not accepted because the engine builds the prompt." }, "minItems": 1, "type": "array" }, "metadata": { "additionalProperties": {}, "description": "Your own data about the conversation, as an object. It goes to the prompt of every turn, so the model reads it and it costs tokens each time. The key `prompt` is put first as plain text; the other keys go as JSON; `scratchpad` is not shown.", "propertyNames": { "type": "string" }, "type": "object" }, "resource": { "description": "Your own id for the end user (for example a customer id). The server creates or reuses the contact of that user. A later agent run on this thread with the same `resource` is accepted.", "maxLength": 255, "minLength": 1, "type": "string" } }, "required": ["agent_id"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent of the thread.", "type": "string" }, "ai_enabled": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the AI answers in this thread. `null` on `chatwoot` and `crm` threads, where the AI state is managed in Chatwoot." }, "channel": { "description": "Channel of the conversation. `crm` is the CRM connected to the agent.", "enum": ["api", "dashboard", "whatsapp", "crm", "chatwoot"], "type": "string" }, "created": { "description": "true when this call created the thread; false when it found the existing conversation of that channel.", "type": "boolean" }, "created_at": { "description": "When the thread 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" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "`evals` for an evals thread; `null` for production. It never changes." }, "id": { "description": "Id of the thread; the same id as `memory.thread` of an agent run.", "type": "string" }, "messages": { "description": "Messages stored by this call, in the order you sent them; empty when you sent none.", "items": { "properties": { "created_at": { "description": "When the message was stored (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" }, "id": { "description": "Id of the stored message.", "type": "string" }, "role": { "description": "Author of the message.", "enum": ["user", "assistant"], "type": "string" }, "thread_id": { "description": "Id of the thread the message was stored in.", "type": "string" }, "type": { "const": "thread_message", "description": "Object type, always `thread_message`.", "type": "string" } }, "required": ["type", "id", "thread_id", "role", "created_at"], "type": "object" }, "type": "array" }, "metadata": { "additionalProperties": {}, "description": "Your data about the conversation; `{}` when there is none.", "propertyNames": { "type": "string" }, "type": "object" }, "resource": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Your id for the end user (`resource`) of the contact that owns the thread; `null` when there is none." }, "type": { "const": "thread", "description": "Object type, always `thread`.", "type": "string" }, "updated_at": { "description": "When the thread 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" } }, "required": ["type", "id", "agent_id", "channel", "resource", "metadata", "environment", "ai_enabled", "created_at", "updated_at", "created", "messages"], "type": "object" } },
|
|
23
|
+
"threads.create": { "body": { "additionalProperties": false, "properties": { "agent_id": { "description": "Id of the agent that will answer in this thread.", "minLength": 1, "type": "string" }, "channel": { "anyOf": [{ "additionalProperties": false, "description": "Link the thread to a WhatsApp conversation, so replies and follow-ups reach the customer. The conversation is created if it does not exist.", "properties": { "phone_number_id": { "description": "Id of the WhatsApp number (`phone_number_id` of Meta) that sent the template. It must be a WhatsApp number of your organization connected to this same agent.", "minLength": 1, "type": "string" }, "to": { "description": "Identifier of the customer that Meta returned when the template was sent: `contacts[0].wa_id` (digits only, no `+` or spaces) or `contacts[0].user_id` (a BSUID such as `AR.123456`). If Meta returns both, send the `wa_id`. Anything else is rejected.", "type": "string" }, "type": { "const": "whatsapp", "description": "Channel type, always `whatsapp`.", "type": "string" } }, "required": ["type", "phone_number_id", "to"], "type": "object" }, { "additionalProperties": false, "description": "Link the thread to a conversation of the CRM connected to the agent.", "properties": { "account_id": { "description": "Id of the account in the CRM that owns the conversation.", "minLength": 1, "type": "string" }, "conversation_id": { "description": "Id of the conversation in the CRM, as the CRM reports it. It is not the id of the contact nor one you make up: the template must have been sent through the CRM so that the conversation exists.", "minLength": 1, "type": "string" }, "type": { "const": "crm", "description": "Channel type, always `crm`.", "type": "string" } }, "required": ["type", "account_id", "conversation_id"], "type": "object" }, { "additionalProperties": false, "description": "Link the thread to a Chatwoot conversation of the agent.", "properties": { "conversation_id": { "description": "Id of the conversation in Chatwoot, as Chatwoot reports it. It is not the id of the contact nor one you make up: the template must have been sent through Chatwoot so that the conversation exists.", "minLength": 1, "type": "string" }, "type": { "const": "chatwoot", "description": "Channel type, always `chatwoot`.", "type": "string" } }, "required": ["type", "conversation_id"], "type": "object" }], "description": "The channel conversation the thread must be linked to. The channel type is the `type` field; each type accepts only its own fields." }, "contact": { "additionalProperties": false, "description": "Profile of the end user, used only when `resource` creates a new contact. Fields that clash with another contact are left out, without warning.", "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" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "Creates an evals thread: runs on it must send the same `environment`, as in an agent run. Omit it, or send `null`, for production. It cannot go with `channel`, because a channel conversation is a real one: it returns 400 `invalid_request` with `details.reason` `channel_conversation_is_real`." }, "messages": { "description": "Messages to store when the thread is created, in the order you send them, with no limit on the number of messages, but the whole request body is capped at about 1 MB (a bigger one gets 413): send long histories in several calls. Storing messages does not run the agent: run it on this thread afterwards (send `memory.thread` in an agent run, or use `laburen agents run --thread`).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A message of the end user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. A message needs some text or at least one file.", "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` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, { "additionalProperties": false, "description": "A message of the agent.", "properties": { "parts": { "description": "Content of the message: text parts only. File parts are rejected in an `assistant` message.", "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": { "const": "assistant", "description": "Author of the message, always `assistant` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }], "description": "A message to store in the thread. `role` is `user` or `assistant`; `system` is not accepted because the engine builds the prompt." }, "minItems": 1, "type": "array" }, "metadata": { "additionalProperties": {}, "description": "Your own data about the conversation, as an object. It goes to the prompt of every turn, so the model reads it and it costs tokens each time. The key `prompt` is put first as plain text; the other keys go as JSON; `scratchpad` is not shown.", "propertyNames": { "type": "string" }, "type": "object" }, "resource": { "description": "Your own id for the end user (for example a customer id). The server creates or reuses the contact of that user. A later agent run on this thread with the same `resource` is accepted.", "maxLength": 255, "minLength": 1, "type": "string" } }, "required": ["agent_id"], "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent of the thread.", "type": "string" }, "ai_enabled": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the AI answers in this thread. `null` on `chatwoot` and `crm` threads, where the AI state is managed in Chatwoot." }, "channel": { "description": "Channel of the conversation. `crm` is the CRM connected to the agent.", "enum": ["api", "dashboard", "whatsapp", "crm", "chatwoot"], "type": "string" }, "created": { "description": "true when this call created the thread; false when it found the existing conversation of that channel.", "type": "boolean" }, "created_at": { "description": "When the thread 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" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "`evals` for an evals thread; `null` for production. It never changes." }, "id": { "description": "Id of the thread; the same id as `memory.thread` of an agent run.", "type": "string" }, "messages": { "description": "Messages stored by this call, in the order you sent them; empty when you sent none.", "items": { "properties": { "created_at": { "description": "When the message was stored (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" }, "id": { "description": "Id of the stored message.", "type": "string" }, "role": { "description": "Author of the message.", "enum": ["user", "assistant"], "type": "string" }, "thread_id": { "description": "Id of the thread the message was stored in.", "type": "string" }, "type": { "const": "thread_message", "description": "Object type, always `thread_message`.", "type": "string" } }, "required": ["type", "id", "thread_id", "role", "created_at"], "type": "object" }, "type": "array" }, "metadata": { "additionalProperties": {}, "description": "Your data about the conversation; `{}` when there is none.", "propertyNames": { "type": "string" }, "type": "object" }, "resource": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Your id for the end user (`resource`) of the contact that owns the thread; `null` when there is none." }, "type": { "const": "thread", "description": "Object type, always `thread`.", "type": "string" }, "updated_at": { "description": "When the thread 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" } }, "required": ["type", "id", "agent_id", "channel", "resource", "metadata", "environment", "ai_enabled", "created_at", "updated_at", "created", "messages"], "type": "object" } },
|
|
23
24
|
"threads.messages.create": { "body": { "additionalProperties": false, "properties": { "messages": { "description": "Messages to add at the end of the thread, in the order you send them, with no limit on the number of messages, but the whole request body is capped at about 1 MB (a bigger one gets 413): send long histories in several calls. Storing them does not run the agent: run it on this thread afterwards (send `memory.thread` in an agent run, or use `laburen agents run --thread`).", "items": { "anyOf": [{ "additionalProperties": false, "description": "A message of the end user.", "properties": { "parts": { "description": "Content of the message: text parts and file parts, in order. A message needs some text or at least one file.", "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` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }, { "additionalProperties": false, "description": "A message of the agent.", "properties": { "parts": { "description": "Content of the message: text parts only. File parts are rejected in an `assistant` message.", "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": { "const": "assistant", "description": "Author of the message, always `assistant` here.", "type": "string" } }, "required": ["role", "parts"], "type": "object" }], "description": "A message to store in the thread. `role` is `user` or `assistant`; `system` is not accepted because the engine builds the prompt." }, "minItems": 1, "type": "array" } }, "required": ["messages"], "type": "object" }, "response": { "properties": { "messages": { "description": "Messages stored by this call, in the order you sent them.", "items": { "properties": { "created_at": { "description": "When the message was stored (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" }, "id": { "description": "Id of the stored message.", "type": "string" }, "role": { "description": "Author of the message.", "enum": ["user", "assistant"], "type": "string" }, "thread_id": { "description": "Id of the thread the message was stored in.", "type": "string" }, "type": { "const": "thread_message", "description": "Object type, always `thread_message`.", "type": "string" } }, "required": ["type", "id", "thread_id", "role", "created_at"], "type": "object" }, "type": "array" }, "type": { "const": "thread_messages_created", "description": "Object type, always `thread_messages_created`.", "type": "string" } }, "required": ["type", "messages"], "type": "object" } },
|
|
24
25
|
"threads.update": { "body": { "additionalProperties": false, "properties": { "ai_enabled": { "description": "Turn the AI of the thread on (`true`) or off (`false`). `true` also moves a thread waiting for a human back to unresolved; `false` hands it to a human, without the email that the `request_human` tool sends. Rejected on `chatwoot` and `crm` threads, where the AI state is managed in Chatwoot: it returns 400 `invalid_request` with `details.reason` `ai_status_managed_by_channel`, and nothing is changed. Sending the value the thread already has changes nothing.", "type": "boolean" }, "metadata": { "additionalProperties": {}, "description": "Keys to change in the metadata. Merged by top-level key: the keys you send are set, the others stay. A key with `null` is deleted. A value that is an object replaces the previous value whole, it is not merged inside. The metadata goes to the prompt of every turn, so the model reads it and it costs tokens each time; the key `prompt` is put first as plain text. Without it (or with `{}`) nothing changes and the thread comes back as it is.", "propertyNames": { "type": "string" }, "type": "object" } }, "type": "object" }, "response": { "properties": { "agent_id": { "description": "Id of the agent of the thread.", "type": "string" }, "ai_enabled": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether the AI answers in this thread. `null` on `chatwoot` and `crm` threads, where the AI state is managed in Chatwoot." }, "channel": { "description": "Channel of the conversation. `crm` is the CRM connected to the agent.", "enum": ["api", "dashboard", "whatsapp", "crm", "chatwoot"], "type": "string" }, "created_at": { "description": "When the thread 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" }, "environment": { "anyOf": [{ "enum": ["evals"], "type": "string" }, { "type": "null" }], "description": "`evals` for an evals thread; `null` for production. It never changes." }, "id": { "description": "Id of the thread; the same id as `memory.thread` of an agent run.", "type": "string" }, "metadata": { "additionalProperties": {}, "description": "Your data about the conversation; `{}` when there is none.", "propertyNames": { "type": "string" }, "type": "object" }, "resource": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Your id for the end user (`resource`) of the contact that owns the thread; `null` when there is none." }, "type": { "const": "thread", "description": "Object type, always `thread`.", "type": "string" }, "updated_at": { "description": "When the thread 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" } }, "required": ["type", "id", "agent_id", "channel", "resource", "metadata", "environment", "ai_enabled", "created_at", "updated_at"], "type": "object" } },
|
|
25
26
|
"tokens.create": { "body": { "additionalProperties": false, "properties": { "all_organizations": { "description": "For a personal token: make it work in every organization you belong to. Then X-Laburen-Organization is required on each call.", "type": "boolean" }, "description": { "description": "What the token is used for (up to 500 characters).", "maxLength": 500, "type": "string" }, "expires_at": { "description": "When the token expires (RFC 3339). When omitted, it does not expire.", "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" }, "kind": { "description": "`personal` acts as you; `organization` acts as the organization and needs admin.", "enum": ["personal", "organization"], "type": "string" }, "name": { "description": "Name of the token (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" }, "permissions": { "description": "Permissions to grant. They cannot exceed your own.", "items": { "description": "Permission level: `query`, `read`, `write` or `admin`.", "enum": ["query", "read", "write", "admin"], "type": "string" }, "type": "array" } }, "required": ["kind", "permissions", "name"], "type": "object" }, "response": { "properties": { "created_at": { "description": "When the token 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 token.", "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "What the token is used for; `null` when there is none." }, "expires_at": { "anyOf": [{ "description": "When the token expires (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" }, { "type": "null" }], "description": "When the token expires (RFC 3339); `null` if it does not expire." }, "id": { "description": "Id of the token.", "type": "string" }, "kind": { "description": "`personal` acts as a user; `organization` acts as the organization itself.", "enum": ["personal", "organization"], "type": "string" }, "last_used_at": { "anyOf": [{ "description": "When the token was last used (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" }, { "type": "null" }], "description": "When the token was last used (RFC 3339); `null` if it never was." }, "name": { "description": "Name of the token.", "type": "string" }, "organization_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the organization the token is limited to; `null` for a personal token of all organizations." }, "permissions": { "description": "Permissions the token grants.", "items": { "description": "Permission level: `query`, `read`, `write` or `admin`.", "enum": ["query", "read", "write", "admin"], "type": "string" }, "type": "array" }, "prefix": { "description": "First characters of the token value, to recognize it.", "type": "string" }, "revoked_at": { "anyOf": [{ "description": "When the token was revoked (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" }, { "type": "null" }], "description": "When the token was revoked (RFC 3339); `null` if it is still valid." }, "suffix": { "description": "Last characters of the token value, to recognize it.", "type": "string" }, "type": { "const": "token", "description": "Object type, always `token`.", "type": "string" }, "user_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the user the token belongs to; `null` for an organization token." }, "value": { "description": "The token secret, returned once in this response. Store it now: it cannot be read again.", "type": "string" } }, "required": ["type", "id", "kind", "user_id", "organization_id", "permissions", "prefix", "suffix", "name", "description", "last_used_at", "expires_at", "revoked_at", "created_by", "created_at", "value"], "type": "object" } },
|
|
26
27
|
"tokens.update": { "body": { "additionalProperties": false, "properties": { "description": { "anyOf": [{ "description": "What the token is used for (up to 500 characters).", "maxLength": 500, "type": "string" }, { "type": "null" }], "description": "New description; `null` clears it." }, "name": { "description": "Name of the token (1 to 100 characters).", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" }, "response": { "properties": { "created_at": { "description": "When the token 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 token.", "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "What the token is used for; `null` when there is none." }, "expires_at": { "anyOf": [{ "description": "When the token expires (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" }, { "type": "null" }], "description": "When the token expires (RFC 3339); `null` if it does not expire." }, "id": { "description": "Id of the token.", "type": "string" }, "kind": { "description": "`personal` acts as a user; `organization` acts as the organization itself.", "enum": ["personal", "organization"], "type": "string" }, "last_used_at": { "anyOf": [{ "description": "When the token was last used (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" }, { "type": "null" }], "description": "When the token was last used (RFC 3339); `null` if it never was." }, "name": { "description": "Name of the token.", "type": "string" }, "organization_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the organization the token is limited to; `null` for a personal token of all organizations." }, "permissions": { "description": "Permissions the token grants.", "items": { "description": "Permission level: `query`, `read`, `write` or `admin`.", "enum": ["query", "read", "write", "admin"], "type": "string" }, "type": "array" }, "prefix": { "description": "First characters of the token value, to recognize it.", "type": "string" }, "revoked_at": { "anyOf": [{ "description": "When the token was revoked (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" }, { "type": "null" }], "description": "When the token was revoked (RFC 3339); `null` if it is still valid." }, "suffix": { "description": "Last characters of the token value, to recognize it.", "type": "string" }, "type": { "const": "token", "description": "Object type, always `token`.", "type": "string" }, "user_id": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Id of the user the token belongs to; `null` for an organization token." } }, "required": ["type", "id", "kind", "user_id", "organization_id", "permissions", "prefix", "suffix", "name", "description", "last_used_at", "expires_at", "revoked_at", "created_by", "created_at"], "type": "object" } },
|
|
27
28
|
};
|
|
29
|
+
/** El `summary` del contrato de las operaciones que son comandos a mano. */
|
|
30
|
+
export const OPERATION_SUMMARIES = {
|
|
31
|
+
"agents.generate": "Run one turn of an agent and return the full result. A conversation with the AI turned off fails with `ai_disabled_for_conversation`; the message is saved anyway and the error's `details.message_id` is its id.",
|
|
32
|
+
"agents.generateFollowUp": "Simulate a follow-up of an agent on a disposable copy of a conversation, without sending anything. Only missing credits stop it. The tools run for real: if one creates a booking, the booking is created.",
|
|
33
|
+
"agents.sendMessage": "Queue a message for an agent and get the answer at a webhook. The agent waits `inbound.debounce_ms` of its active version (0 without `inbound`) and answers the messages that arrived meanwhile with one turn. Only conversations created through the API are accepted. An agent without an active version (`invalid_agent_config`) or a conversation with the AI turned off (`ai_disabled_for_conversation`) fails here, when the message arrives (with the AI turned off the message is saved anyway, and `details.message_id` is its id). If it changes while the message waits, it arrives as `agent.error`.",
|
|
34
|
+
"agents.stream": "Run one turn of an agent and stream it as an AI SDK UI message stream (v1).",
|
|
35
|
+
};
|
|
36
|
+
/** Por evento que la API manda a una `webhook_url` (clave `webhooks` del contrato): sus headers y su cuerpo. */
|
|
37
|
+
export const WEBHOOK_SCHEMAS = {
|
|
38
|
+
"agent.error": { "description": "Sent to the `webhook_url` of `agents.sendMessage` when the turn fails: no credits, AI turned off, no active version, a model error. The body is the error body of the API, plus `message_ids`. Its `request_id` is the `request-id` header. There is no signature and no retry.", "headers": [{ "description": "Always `agent.error`.", "in": "header", "name": "X-Laburen-Event", "required": true, "schema": { "enum": ["agent.error"], "type": "string" } }, { "description": "Id of this run of the job, `req_` and an id. It is also the `request_id` of an `agent.error`; quote it when asking for help.", "in": "header", "name": "request-id", "required": true, "schema": { "type": "string" } }, { "description": "Always `Laburen-Webhook/1`.", "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": ["Laburen-Webhook/1"], "type": "string" } }, { "description": "\"true\" if sending the same messages again may succeed; \"false\" if not. Same meaning as in the error responses of the API.", "in": "header", "name": "x-should-retry", "required": true, "schema": { "enum": ["true", "false"], "type": "string" } }], "body": { "properties": { "error": { "description": "The error.", "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" }, "issues": { "description": "Every invalid field of the request; present only on validation errors.", "items": { "description": "A validation problem in one field.", "properties": { "field": { "description": "Path of the invalid field, for example `config.model.id`.", "type": "string" }, "message": { "description": "What is wrong with that field.", "type": "string" } }, "required": ["field", "message"], "type": "object" }, "type": "array" }, "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" }, "message_ids": { "description": "Ids of the messages this event is about, in order: the `message_id` of each `queued_message` the turn answers.", "items": { "type": "string" }, "type": "array" }, "request_id": { "description": "Id of the request; quote it when asking for help.", "type": "string" }, "type": { "const": "error", "description": "Object type, always `error`.", "type": "string" } }, "required": ["type", "error", "request_id", "message_ids"], "type": "object" } },
|
|
39
|
+
"agent.response": { "description": "Sent to the `webhook_url` of `agents.sendMessage` when the turn that answers the queued messages finishes. The body is the same `agent_run` that `agents.generate` returns, plus `message_ids`. There is no signature and no retry.", "headers": [{ "description": "Always `agent.response`.", "in": "header", "name": "X-Laburen-Event", "required": true, "schema": { "enum": ["agent.response"], "type": "string" } }, { "description": "Id of this run of the job, `req_` and an id. It is also the `request_id` of an `agent.error`; quote it when asking for help.", "in": "header", "name": "request-id", "required": true, "schema": { "type": "string" } }, { "description": "Always `Laburen-Webhook/1`.", "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": ["Laburen-Webhook/1"], "type": "string" } }], "body": { "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." }, "message_ids": { "description": "Ids of the messages this event is about, in order: the `message_id` of each `queued_message` the turn answers. Not to be confused with `message_id`, the stored answer.", "items": { "type": "string" }, "type": "array" }, "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", "message_ids"], "type": "object" } },
|
|
40
|
+
};
|
|
28
41
|
//# sourceMappingURL=schemas.js.map
|