> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/documentation/api-reference-alpha/reference/agents.md).

# Agents

## GET /api/v1/agents

> Retrieves multiple agents.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents":{"get":{"description":"Retrieves multiple agents.","tags":["Agents"],"parameters":[{"schema":{"anyOf":[{"type":"array","items":{"type":"string","enum":["squads"]}},{"type":"string","enum":["squads"]}],"default":[]},"required":false,"name":"joins","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"description":"The page number."},"required":false,"description":"The page number.","name":"pageNumber","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"The page size."},"required":false,"description":"The page size.","name":"pageSize","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"referenceIds","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Search term to filter agents by name, internal name, role, or prompt."},"required":false,"description":"Search term to filter agents by name, internal name, role, or prompt.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"squadIds","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"versionIds","in":"query"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"Retrieves all agents for the workspace.","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this agent was last executed."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice to use for audio responses. Null when disabled for the agent."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the agent."},"squadAgents":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"agentId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"squadId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"type":{"type":"string","enum":["member","main"]},"squad":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"description":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"The internal description of the squad."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this squad was last executed."},"mode":{"type":"string","enum":["hierarchical","flat"],"description":"The management mode. In flat, agents redirect the chat to one another. In hierarchical, all iterations are intermediated by the manager."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the squad."},"picture":{"type":"string","nullable":true,"description":"The picture associated with the squad."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the squad."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the squad."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","description","lastExecutedAt","mode","name","picture","superIdentityId","workspaceId"]}},"required":["createdAt","updatedAt","agentId","squadId","type","squad"]}}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","codeRuntime","internalName","iterations","lastExecutedAt","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","superIdentityId","temperature","timezone","toolCount","voiceId","workspaceId","squadAgents"]},{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this agent was last executed."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice to use for audio responses. Null when disabled for the agent."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the agent."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","codeRuntime","internalName","iterations","lastExecutedAt","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","superIdentityId","temperature","timezone","toolCount","voiceId","workspaceId"]}]}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## POST /api/v1/agents

> Creates a new agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents":{"post":{"description":"Creates a new agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."}},"required":["codeRuntime","internalName","iterations","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","temperature","timezone"]}}}},"responses":{"200":{"description":"The agent was created.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this agent was last executed."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice to use for audio responses. Null when disabled for the agent."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the agent."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","codeRuntime","internalName","iterations","lastExecutedAt","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","superIdentityId","temperature","timezone","toolCount","voiceId","workspaceId"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"403":{"description":"Plan limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## POST /api/v1/agents/{agentId}/mcps

> Creates a new MCP or attaches an existing one to an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{agentId}/mcps":{"post":{"description":"Creates a new MCP or attaches an existing one to an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"agentId","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"mcp":{"type":"object","properties":{"connectionId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the connection the MCP will be used through."},"description":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"The internal description of the MCP."},"detail":{"oneOf":[{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"},"minItems":1},"type":{"type":"string","enum":["composio-airtable","composio-asana","composio-bannerbear","composio-browseai","composio-browser-tool","composio-calendly","composio-clickup","composio-discord","composio-dropbox","composio-facebook","composio-figma","composio-genderize","composio-github","composio-gitlab","composio-gmail","composio-google-analytics","composio-google-calendar","composio-google-docs","composio-google-drive","composio-google-maps","composio-google-meet","composio-google-sheets","composio-google-slides","composio-google-tasks","composio-hubspot","composio-hugging-face","composio-instagram","composio-linear","composio-linkedin","composio-mailersend","composio-manus","composio-mem0","composio-meta-ads","composio-microsoft-clarity","composio-miro","composio-mixpanel","composio-monday","composio-notion","composio-one-drive","composio-openweather-api","composio-outlook","composio-polygon-io","composio-postman","composio-prisma","composio-pushbullet","composio-reddit","composio-resend","composio-salesforce","composio-scrape-do","composio-search-api","composio-sendgrid","composio-sentry","composio-serpapi","composio-short-io","composio-short-menu","composio-slack","composio-slackbot","composio-stripe","composio-supabase","composio-tavily","composio-teams","composio-telegram","composio-ticktick","composio-todoist","composio-trello","composio-twitter","composio-typeform","composio-youtube","composio-zenrows"]}},"required":["tools","type"]}]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the MCP."}},"required":["connectionId","description","detail","name"]}},"required":["mcp"]},{"type":"object","properties":{"mcpId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"required":["mcpId"]}]}}}},"responses":{"200":{"description":"The MCP was created or linked to the agent.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"agentId":{"type":"string","format":"uuid","description":"The id of the agent to link the MCP to."},"mcpId":{"type":"string","format":"uuid","description":"The id of the MCP to link to the agent."},"mcp":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"connectionId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the connection the MCP will be used through."},"description":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"The internal description of the MCP."},"detail":{"oneOf":[{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"},"minItems":1},"type":{"type":"string","enum":["composio-airtable","composio-asana","composio-bannerbear","composio-browseai","composio-browser-tool","composio-calendly","composio-clickup","composio-discord","composio-dropbox","composio-facebook","composio-figma","composio-genderize","composio-github","composio-gitlab","composio-gmail","composio-google-analytics","composio-google-calendar","composio-google-docs","composio-google-drive","composio-google-maps","composio-google-meet","composio-google-sheets","composio-google-slides","composio-google-tasks","composio-hubspot","composio-hugging-face","composio-instagram","composio-linear","composio-linkedin","composio-mailersend","composio-manus","composio-mem0","composio-meta-ads","composio-microsoft-clarity","composio-miro","composio-mixpanel","composio-monday","composio-notion","composio-one-drive","composio-openweather-api","composio-outlook","composio-polygon-io","composio-postman","composio-prisma","composio-pushbullet","composio-reddit","composio-resend","composio-salesforce","composio-scrape-do","composio-search-api","composio-sendgrid","composio-sentry","composio-serpapi","composio-short-io","composio-short-menu","composio-slack","composio-slackbot","composio-stripe","composio-supabase","composio-tavily","composio-teams","composio-telegram","composio-ticktick","composio-todoist","composio-trello","composio-twitter","composio-typeform","composio-youtube","composio-zenrows"]}},"required":["tools","type"]}]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the MCP."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the MCP."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","connectionId","description","detail","name","workspaceId"]}},"required":["createdAt","updatedAt","agentId","mcpId","mcp"]}}}},"400":{"description":"Connection type is not compatible with MCP type.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"The agent, MCP, or connection was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"412":{"description":"MCP is already associated with this agent.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## POST /api/v1/agents/{agentId}/tools

> Creates a new tool or attaches an existing one to an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{agentId}/tools":{"post":{"description":"Creates a new tool or attaches an existing one to an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"agentId","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"tool":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":250,"description":"The internal description of the tool."},"detail":{"anyOf":[{"type":"object","properties":{"allowedDomains":{"type":"array","items":{"type":"string","minLength":1},"description":"List of domains allowed in web search results."},"effort":{"type":"string","enum":["low","medium","high"],"description":"Web search effort level."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional OpenAI LLM provider ID to be used in this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be appended alongside queries to instruct the LLM call."},"type":{"type":"string","enum":["agentic-web-search"]}},"required":["allowedDomains","effort","execution","llmProviderId","prompt","type"]},{"type":"object","properties":{"body":{"type":"string","nullable":true,"maxLength":10000,"description":"The body of the HTTP request as JSON string."},"headers":{"type":"string","nullable":true,"maxLength":2000,"description":"The headers of the HTTP request as JSON string."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"parameters":{"type":"object","description":"The JSON Schema definition of the parameters that will be passed to the HTTP request.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"query":{"type":"string","nullable":true,"maxLength":1000,"description":"The query parameters of the HTTP request as JSON string."},"type":{"type":"string","enum":["http-request"]},"url":{"type":"string","maxLength":500,"format":"uri","description":"The URL to send the HTTP request to. Should not contain query parameters."}},"required":["body","headers","method","parameters","query","type","url"]},{"type":"object","properties":{"code":{"type":"string","maxLength":3000,"description":"The code to be executed. Must contain a function named main that takes no parameters."},"parameters":{"type":"object","description":"The JSON Schema definition of the parameters that will be passed to the code execution tool.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"type":{"type":"string","enum":["code-execution"]}},"required":["code","parameters","type"]},{"type":"object","properties":{"parameters":{"type":"object","description":"The JSON Schema definition of the parameters containing the description of the memory to be stored.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"sensitiveParameters":{"type":"array","items":{"type":"string"},"description":"Wheter the parameters are sensitive and should not be shown."},"type":{"type":"string","enum":["contextual-memory"]}},"required":["parameters","sensitiveParameters","type"]},{"type":"object","properties":{"datasetId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the dataset to search in."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"mode":{"type":"string","enum":["scoped","global"],"description":"The mode of the dataset search."},"type":{"type":"string","enum":["dataset-search"]}},"required":["datasetId","execution","mode","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to update the row in."},"type":{"type":"string","enum":["datagrid-row-update"]}},"required":["datagridId","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to insert the row into."},"type":{"type":"string","enum":["datagrid-row-insertion"]}},"required":["datagridId","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to search the row in."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"results":{"type":"number","description":"The number of results to return to the agent."},"type":{"type":"string","enum":["datagrid-row-semantic-search"]}},"required":["datagridId","execution","results","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to search the row in."},"results":{"type":"number","description":"The number of results to return to the agent."},"type":{"type":"string","enum":["datagrid-row-similarity-search"]}},"required":["datagridId","results","type"]},{"type":"object","properties":{"tagging":{"type":"object","properties":{"allowedIds":{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"status":{"type":"string","enum":["enabled","disabled"]}},"required":["allowedIds","status"],"description":"Tagging configuration for tickets."},"ticketingTeamId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the ticketing team responsible for the ticket."},"type":{"type":"string","enum":["ticket-creation"]}},"required":["tagging","ticketingTeamId","type"]},{"type":"object","properties":{"tagging":{"type":"object","properties":{"allowedIds":{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"status":{"type":"string","enum":["enabled","disabled"]}},"required":["allowedIds","status"],"description":"Tagging configuration for chats."},"type":{"type":"string","enum":["chat-tagging"]}},"required":["tagging","type"]},{"type":"object","properties":{"path":{"type":"string","nullable":true,"description":"The path of the trigger to the workflow implementation to execute."},"type":{"type":"string","enum":["workflow-executor"]}},"required":["path","type"]},{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":1000,"description":"Instructions describing what should be scheduled and when."},"target":{"type":"object","properties":{"path":{"type":"string","nullable":true,"description":"The path of the workflow trigger to schedule."},"type":{"type":"string","enum":["workflow"]}},"required":["path","type"]},"type":{"type":"string","enum":["schedule"]}},"required":["prompt","target","type"]},{"type":"object","properties":{"file":{"type":"string","minLength":1},"fileName":{"type":"string","minLength":1,"description":"The name of the PDF file."},"type":{"type":"string","enum":["pdf-reader"]}},"required":["file","fileName","type"]},{"type":"object","properties":{"execution":{"type":"string","enum":["eligible","compulsory"]},"fallback":{"type":"object","nullable":true,"properties":{"prompt":{"type":"string","minLength":1,"maxLength":1000}},"required":["prompt"]},"options":{"type":"array","items":{"type":"object","properties":{"condition":{"type":"string","minLength":3,"maxLength":250},"label":{"type":"string","minLength":1,"maxLength":50},"prompt":{"type":"string","minLength":1,"maxLength":1000}},"required":["condition","label","prompt"]}},"type":{"type":"string","enum":["follow-up"]}},"required":["execution","fallback","options","type"]},{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","description":"The ID of the messaging connection to use."},"mode":{"type":"string","enum":["discover","preset"],"description":"The execution mode."},"phoneNumbers":{"type":"array","items":{"type":"object","properties":{"ddi":{"type":"string","description":"The DDI of the phone number."},"phoneNumber":{"type":"string","description":"The phone number to send the message to including the state prefix."}},"required":["ddi","phoneNumber"]},"description":"List of phone numbers for preset mode. Can be an empty array for discover mode."},"sendMode":{"type":"string","enum":["text","text-with-template-fallback","template"],"description":"The message sending mode."},"template":{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"parameterName":{"type":"string"},"value":{"type":"string"}},"required":["parameterName","value"]},"default":[]}}},"buttons":{"type":"object","properties":{"texts":{"type":"array","items":{"type":"string","maxLength":25}},"urlVariables":{"type":"array","items":{"type":"object","properties":{"buttonIndex":{"type":"integer","minimum":0},"value":{"type":"string","maxLength":2000}},"required":["buttonIndex","value"]}}}},"category":{"type":"string","nullable":true,"enum":["AUTHENTICATION","MARKETING","UTILITY",null]},"footer":{"type":"string","maxLength":60},"header":{"type":"object","properties":{"imageUrl":{"type":"string"},"text":{"type":"string","maxLength":60},"variables":{"type":"array","items":{"type":"object","properties":{"parameterName":{"type":"string"},"value":{"type":"string"}},"required":["parameterName","value"]}}}},"language":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["language","name"]},"templatePayloadSchema":{"type":"object","description":"A JSON Schema definition object","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"type":{"type":"string","enum":["message-dispatch"]}},"required":["connectionId","mode","phoneNumbers","sendMode","type"]},{"type":"object","properties":{"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional LLM provider ID to be used in this tool call."},"model":{"type":"string","enum":["gpt-image-1","gpt-image-2"],"description":"OpenAI image model to use for this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be prepended to image generation calls."},"provider":{"type":"string","enum":["openai"],"description":"Image generation provider to use for this tool call."},"type":{"type":"string","enum":["image-generation"]}},"required":["llmProviderId","model","prompt","provider","type"]},{"type":"object","properties":{"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional LLM provider ID to be used in this tool call."},"model":{"type":"string","enum":["gemini-3.1-flash-image","gemini-3-pro-image"],"description":"Gemini image model to use for this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be prepended to image generation calls."},"provider":{"type":"string","enum":["google-ai"],"description":"Image generation provider to use for this tool call."},"type":{"type":"string","enum":["image-generation"]}},"required":["llmProviderId","model","prompt","provider","type"]},{"type":"object","properties":{"delay":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":60000,"description":"An optional delay in milliseconds to be waited after the event is emitted and, if applicable, a response is received."},"event":{"type":"string","minLength":3,"maxLength":50,"pattern":"^[A-Za-z0-9_-]+$","description":"The name of the client-side event to listen for."},"mock":{"type":"object","properties":{"delay":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":60000,"description":"An optional delay in milliseconds before returning the mock response when testing."},"response":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"An optional mock response to be returned when testing."}},"required":["delay","response"],"description":"Optional mock configuration for testing purposes."},"parameters":{"type":"object","description":"The JSON schema of the parameters to pass with the event.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"payload":{"type":"string","nullable":true,"description":"An optional payload to bind parameters to."},"timeout":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":300000,"description":"The maximum time in milliseconds to wait for a response before timing out."},"type":{"type":"string","enum":["client-side-call"]},"waitResponse":{"type":"boolean","description":"Whether to wait for a response after emitting the event."}},"required":["delay","event","mock","parameters","payload","timeout","type","waitResponse"]}]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the tool."}},"required":["description","detail","name"]}},"required":["tool"]},{"type":"object","properties":{"toolId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"required":["toolId"]}]}}}},"responses":{"200":{"description":"The tool was created or linked to the agent.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"agentId":{"type":"string","format":"uuid","description":"The id of the agent to link the tool to."},"toolId":{"type":"string","format":"uuid","description":"The id of the tool to link to the agent."},"tool":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"description":{"type":"string","minLength":3,"maxLength":250,"description":"The internal description of the tool."},"detail":{"anyOf":[{"type":"object","properties":{"allowedDomains":{"type":"array","items":{"type":"string","minLength":1},"description":"List of domains allowed in web search results."},"effort":{"type":"string","enum":["low","medium","high"],"description":"Web search effort level."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional OpenAI LLM provider ID to be used in this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be appended alongside queries to instruct the LLM call."},"type":{"type":"string","enum":["agentic-web-search"]}},"required":["allowedDomains","effort","execution","llmProviderId","prompt","type"]},{"type":"object","properties":{"body":{"type":"string","nullable":true,"maxLength":10000,"description":"The body of the HTTP request as JSON string."},"headers":{"type":"string","nullable":true,"maxLength":2000,"description":"The headers of the HTTP request as JSON string."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"parameters":{"type":"object","description":"The JSON Schema definition of the parameters that will be passed to the HTTP request.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"query":{"type":"string","nullable":true,"maxLength":1000,"description":"The query parameters of the HTTP request as JSON string."},"type":{"type":"string","enum":["http-request"]},"url":{"type":"string","maxLength":500,"format":"uri","description":"The URL to send the HTTP request to. Should not contain query parameters."}},"required":["body","headers","method","parameters","query","type","url"]},{"type":"object","properties":{"code":{"type":"string","maxLength":3000,"description":"The code to be executed. Must contain a function named main that takes no parameters."},"parameters":{"type":"object","description":"The JSON Schema definition of the parameters that will be passed to the code execution tool.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"type":{"type":"string","enum":["code-execution"]}},"required":["code","parameters","type"]},{"type":"object","properties":{"parameters":{"type":"object","description":"The JSON Schema definition of the parameters containing the description of the memory to be stored.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"sensitiveParameters":{"type":"array","items":{"type":"string"},"description":"Wheter the parameters are sensitive and should not be shown."},"type":{"type":"string","enum":["contextual-memory"]}},"required":["parameters","sensitiveParameters","type"]},{"type":"object","properties":{"datasetId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the dataset to search in."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"mode":{"type":"string","enum":["scoped","global"],"description":"The mode of the dataset search."},"type":{"type":"string","enum":["dataset-search"]}},"required":["datasetId","execution","mode","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to update the row in."},"type":{"type":"string","enum":["datagrid-row-update"]}},"required":["datagridId","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to insert the row into."},"type":{"type":"string","enum":["datagrid-row-insertion"]}},"required":["datagridId","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to search the row in."},"execution":{"type":"string","enum":["eligible","compulsory"],"description":"Whether the search should always be executed or only if the agent decides to do it."},"results":{"type":"number","description":"The number of results to return to the agent."},"type":{"type":"string","enum":["datagrid-row-semantic-search"]}},"required":["datagridId","execution","results","type"]},{"type":"object","properties":{"datagridId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the datagrid to search the row in."},"results":{"type":"number","description":"The number of results to return to the agent."},"type":{"type":"string","enum":["datagrid-row-similarity-search"]}},"required":["datagridId","results","type"]},{"type":"object","properties":{"tagging":{"type":"object","properties":{"allowedIds":{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"status":{"type":"string","enum":["enabled","disabled"]}},"required":["allowedIds","status"],"description":"Tagging configuration for tickets."},"ticketingTeamId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the ticketing team responsible for the ticket."},"type":{"type":"string","enum":["ticket-creation"]}},"required":["tagging","ticketingTeamId","type"]},{"type":"object","properties":{"tagging":{"type":"object","properties":{"allowedIds":{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},"status":{"type":"string","enum":["enabled","disabled"]}},"required":["allowedIds","status"],"description":"Tagging configuration for chats."},"type":{"type":"string","enum":["chat-tagging"]}},"required":["tagging","type"]},{"type":"object","properties":{"path":{"type":"string","nullable":true,"description":"The path of the trigger to the workflow implementation to execute."},"type":{"type":"string","enum":["workflow-executor"]}},"required":["path","type"]},{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":1000,"description":"Instructions describing what should be scheduled and when."},"target":{"type":"object","properties":{"path":{"type":"string","nullable":true,"description":"The path of the workflow trigger to schedule."},"type":{"type":"string","enum":["workflow"]}},"required":["path","type"]},"type":{"type":"string","enum":["schedule"]}},"required":["prompt","target","type"]},{"type":"object","properties":{"file":{"type":"string","minLength":1},"fileName":{"type":"string","minLength":1,"description":"The name of the PDF file."},"type":{"type":"string","enum":["pdf-reader"]}},"required":["file","fileName","type"]},{"type":"object","properties":{"execution":{"type":"string","enum":["eligible","compulsory"]},"fallback":{"type":"object","nullable":true,"properties":{"prompt":{"type":"string","minLength":1,"maxLength":1000}},"required":["prompt"]},"options":{"type":"array","items":{"type":"object","properties":{"condition":{"type":"string","minLength":3,"maxLength":250},"label":{"type":"string","minLength":1,"maxLength":50},"prompt":{"type":"string","minLength":1,"maxLength":1000}},"required":["condition","label","prompt"]}},"type":{"type":"string","enum":["follow-up"]}},"required":["execution","fallback","options","type"]},{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","description":"The ID of the messaging connection to use."},"mode":{"type":"string","enum":["discover","preset"],"description":"The execution mode."},"phoneNumbers":{"type":"array","items":{"type":"object","properties":{"ddi":{"type":"string","description":"The DDI of the phone number."},"phoneNumber":{"type":"string","description":"The phone number to send the message to including the state prefix."}},"required":["ddi","phoneNumber"]},"description":"List of phone numbers for preset mode. Can be an empty array for discover mode."},"sendMode":{"type":"string","enum":["text","text-with-template-fallback","template"],"description":"The message sending mode."},"template":{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"parameterName":{"type":"string"},"value":{"type":"string"}},"required":["parameterName","value"]},"default":[]}}},"buttons":{"type":"object","properties":{"texts":{"type":"array","items":{"type":"string","maxLength":25}},"urlVariables":{"type":"array","items":{"type":"object","properties":{"buttonIndex":{"type":"integer","minimum":0},"value":{"type":"string","maxLength":2000}},"required":["buttonIndex","value"]}}}},"category":{"type":"string","nullable":true,"enum":["AUTHENTICATION","MARKETING","UTILITY",null]},"footer":{"type":"string","maxLength":60},"header":{"type":"object","properties":{"imageUrl":{"type":"string"},"text":{"type":"string","maxLength":60},"variables":{"type":"array","items":{"type":"object","properties":{"parameterName":{"type":"string"},"value":{"type":"string"}},"required":["parameterName","value"]}}}},"language":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["language","name"]},"templatePayloadSchema":{"type":"object","description":"A JSON Schema definition object","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"type":{"type":"string","enum":["message-dispatch"]}},"required":["connectionId","mode","phoneNumbers","sendMode","type"]},{"type":"object","properties":{"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional LLM provider ID to be used in this tool call."},"model":{"type":"string","enum":["gpt-image-1","gpt-image-2"],"description":"OpenAI image model to use for this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be prepended to image generation calls."},"provider":{"type":"string","enum":["openai"],"description":"Image generation provider to use for this tool call."},"type":{"type":"string","enum":["image-generation"]}},"required":["llmProviderId","model","prompt","provider","type"]},{"type":"object","properties":{"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"Optional LLM provider ID to be used in this tool call."},"model":{"type":"string","enum":["gemini-3.1-flash-image","gemini-3-pro-image"],"description":"Gemini image model to use for this tool call."},"prompt":{"type":"string","nullable":true,"maxLength":500,"description":"Prompt to be prepended to image generation calls."},"provider":{"type":"string","enum":["google-ai"],"description":"Image generation provider to use for this tool call."},"type":{"type":"string","enum":["image-generation"]}},"required":["llmProviderId","model","prompt","provider","type"]},{"type":"object","properties":{"delay":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":60000,"description":"An optional delay in milliseconds to be waited after the event is emitted and, if applicable, a response is received."},"event":{"type":"string","minLength":3,"maxLength":50,"pattern":"^[A-Za-z0-9_-]+$","description":"The name of the client-side event to listen for."},"mock":{"type":"object","properties":{"delay":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":60000,"description":"An optional delay in milliseconds before returning the mock response when testing."},"response":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"An optional mock response to be returned when testing."}},"required":["delay","response"],"description":"Optional mock configuration for testing purposes."},"parameters":{"type":"object","description":"The JSON schema of the parameters to pass with the event.","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]},"payload":{"type":"string","nullable":true,"description":"An optional payload to bind parameters to."},"timeout":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":300000,"description":"The maximum time in milliseconds to wait for a response before timing out."},"type":{"type":"string","enum":["client-side-call"]},"waitResponse":{"type":"boolean","description":"Whether to wait for a response after emitting the event."}},"required":["delay","event","mock","parameters","payload","timeout","type","waitResponse"]}]},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this tool was last executed."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the tool."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the tool."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","description","detail","lastExecutedAt","name","workspaceId"]}},"required":["createdAt","updatedAt","agentId","toolId","tool"]}}}},"400":{"description":"Invalid tool configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"The agent or tool was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## POST /api/v1/agents/{id}/execute

> Executes an agent with provided messages.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{id}/execute":{"post":{"description":"Executes an agent with provided messages.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"context":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"attachments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"base64":{"type":"string","pattern":"^data:.*;base64,","description":"A base64 encoded string with prefix."},"extension":{"type":"string","enum":["png"]}},"required":["base64","extension"]},{"type":"object","properties":{"base64":{"type":"string","pattern":"^data:.*;base64,","description":"A base64 encoded string with prefix."},"extension":{"type":"string","enum":["pdf"]},"name":{"type":"string"}},"required":["base64","extension"]},{"type":"object","properties":{"base64":{"type":"string","pattern":"^data:.*;base64,","description":"A base64 encoded string with prefix."},"extension":{"type":"string","enum":["md"]}},"required":["base64","extension"]},{"type":"object","properties":{"base64":{"type":"string","pattern":"^data:.*;base64,","description":"A base64 encoded string with prefix."},"extension":{"type":"string","enum":["txt"]}},"required":["base64","extension"]}]}},"content":{"type":"string"},"role":{"anyOf":[{"type":"string","enum":["assistant"]},{"type":"string","enum":["user"]}]}},"required":["attachments","content","role"]},"minItems":1},"output":{"type":"object","description":"A JSON Schema definition object","properties":{"properties":{"additionalProperties":{"oneOf":[{"properties":{"description":{"type":"string"},"enum":{"items":{},"type":"array"},"nullable":{"type":"boolean"},"type":{"enum":["string","number","integer","boolean","null"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"items":{"type":"object"},"nullable":{"type":"boolean"},"type":{"enum":["array"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"description":{"type":"string"},"nullable":{"type":"boolean"},"properties":{"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type"],"type":"object"},{"properties":{"anyOf":{"items":{"type":"object"},"type":"array"},"description":{"type":"string"},"nullable":{"type":"boolean"}},"required":["anyOf"],"type":"object"}]},"type":"object"},"required":{"items":{"type":"string"},"type":"array"},"type":{"enum":["object"],"type":"string"}},"required":["type","properties"]}},"required":["messages"]}}}},"responses":{"200":{"description":"The agent was executed.","content":{"application/json":{"schema":{"type":"object","properties":{"attachmentsUrls":{"type":"array","items":{"type":"string"}},"content":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"nullable":true}}]},"execution":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"creditsUsed":{"type":"number","minimum":0,"description":"The total number of credits used by this execution."},"detail":{"anyOf":[{"type":"object","properties":{"input":{"type":"object","additionalProperties":{"nullable":true},"description":"The input data for this execution."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this execution."},"agentId":{"type":"string","description":"The agent identifier."},"events":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"creditsUsed":{"type":"number","minimum":0,"description":"The number of credits used by this event."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this event ended."},"id":{"type":"string","description":"The event identifier."},"input":{"anyOf":[{"nullable":true},{"type":"object","properties":{}}],"description":"The input data for this event."},"label":{"type":"string","minLength":3,"maxLength":50,"description":"The label for this event."},"llmUsages":{"type":"array","items":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The input token count reported by the LLM provider."},"model":{"type":"string","description":"The model key used for this LLM usage."},"outputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The output token count reported by the LLM provider."},"provider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with this LLM usage."}},"required":["inputTokens","model","outputTokens","provider"]},"description":"The custom-provider LLM usages recorded for this event."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this event."},"startedAt":{"type":"string","format":"date-time","description":"When this event started."},"status":{"type":"string","enum":["running","completed","failed","skipped"],"description":"The status of the event."},"llm":{"type":"string","description":"The model key used during the iteration event."},"llmProvider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with the iteration event."},"type":{"type":"string","enum":["iteration"],"description":"The event subtype represented by this payload."}},"required":["creditsUsed","endedAt","id","label","output","startedAt","status","llm","llmProvider","type"]},{"type":"object","properties":{"creditsUsed":{"type":"number","minimum":0,"description":"The number of credits used by this event."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this event ended."},"id":{"type":"string","description":"The event identifier."},"input":{"anyOf":[{"nullable":true},{"type":"object","properties":{}}],"description":"The input data for this event."},"label":{"type":"string","minLength":3,"maxLength":50,"description":"The label for this event."},"llmUsages":{"type":"array","items":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The input token count reported by the LLM provider."},"model":{"type":"string","description":"The model key used for this LLM usage."},"outputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The output token count reported by the LLM provider."},"provider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with this LLM usage."}},"required":["inputTokens","model","outputTokens","provider"]},"description":"The custom-provider LLM usages recorded for this event."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this event."},"startedAt":{"type":"string","format":"date-time","description":"When this event started."},"status":{"type":"string","enum":["running","completed","failed","skipped"],"description":"The status of the event."},"childExecutionId":{"type":"string","nullable":true,"description":"The child execution identifier."},"toolType":{"type":"string","description":"The type of tool called."},"type":{"type":"string","enum":["tool-call"],"description":"The event subtype represented by this payload."}},"required":["creditsUsed","endedAt","id","label","output","startedAt","status","childExecutionId","toolType","type"]}]},"description":"The events that occurred during this agent execution."},"origin":{"anyOf":[{"type":"object","properties":{"apiKeyId":{"type":"string","description":"The API key identifier."},"type":{"type":"string","enum":["api"],"description":"The execution origin subtype represented by this payload."}},"required":["apiKeyId","type"]},{"type":"object","properties":{"chatMessageId":{"type":"string","description":"The chat message identifier."},"retryOfExecutionId":{"type":"string","description":"The execution identifier of the prior retry attempt."},"type":{"type":"string","enum":["chat-message"],"description":"The execution origin subtype represented by this payload."}},"required":["chatMessageId","type"]},{"type":"object","properties":{"agentId":{"type":"string","description":"The agent identifier."},"type":{"type":"string","enum":["delegation"],"description":"The execution origin subtype represented by this payload."}},"required":["agentId","type"]},{"type":"object","properties":{"type":{"type":"string","enum":["agentic-execution-node"],"description":"The execution origin subtype represented by this payload."},"workflowNodeId":{"type":"string","description":"The workflow node identifier."}},"required":["type","workflowNodeId"]},{"type":"object","properties":{"event":{"type":"string","enum":["comment-created"],"description":"The source event type."},"externalEventId":{"type":"string","description":"The external event identifier."},"source":{"type":"string","enum":["instagram"],"description":"The source event provider."},"triggerId":{"type":"string","description":"The trigger identifier."},"type":{"type":"string","enum":["trigger"],"description":"The execution origin subtype represented by this payload."}},"required":["event","externalEventId","source","triggerId","type"]}],"description":"The origin of this agent execution."},"type":{"type":"string","enum":["agent-execution"],"description":"The execution detail subtype represented by this payload."}},"required":["input","output","agentId","events","origin","type"]},{"type":"object","properties":{"input":{"type":"object","additionalProperties":{"nullable":true},"description":"The input data for this execution."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this execution."},"agentId":{"type":"string","description":"The agent identifier."},"events":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"creditsUsed":{"type":"number","minimum":0,"description":"The number of credits used by this event."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this event ended."},"id":{"type":"string","description":"The event identifier."},"input":{"anyOf":[{"nullable":true},{"type":"object","properties":{}}],"description":"The input data for this event."},"label":{"type":"string","minLength":3,"maxLength":50,"description":"The label for this event."},"llmUsages":{"type":"array","items":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The input token count reported by the LLM provider."},"model":{"type":"string","description":"The model key used for this LLM usage."},"outputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The output token count reported by the LLM provider."},"provider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with this LLM usage."}},"required":["inputTokens","model","outputTokens","provider"]},"description":"The custom-provider LLM usages recorded for this event."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this event."},"startedAt":{"type":"string","format":"date-time","description":"When this event started."},"status":{"type":"string","enum":["running","completed","failed","skipped"],"description":"The status of the event."},"llm":{"type":"string","description":"The model key used during the iteration event."},"llmProvider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with the iteration event."},"type":{"type":"string","enum":["iteration"],"description":"The event subtype represented by this payload."}},"required":["creditsUsed","endedAt","id","label","output","startedAt","status","llm","llmProvider","type"]},{"type":"object","properties":{"creditsUsed":{"type":"number","minimum":0,"description":"The number of credits used by this event."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this event ended."},"id":{"type":"string","description":"The event identifier."},"input":{"anyOf":[{"nullable":true},{"type":"object","properties":{}}],"description":"The input data for this event."},"label":{"type":"string","minLength":3,"maxLength":50,"description":"The label for this event."},"llmUsages":{"type":"array","items":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The input token count reported by the LLM provider."},"model":{"type":"string","description":"The model key used for this LLM usage."},"outputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The output token count reported by the LLM provider."},"provider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with this LLM usage."}},"required":["inputTokens","model","outputTokens","provider"]},"description":"The custom-provider LLM usages recorded for this event."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this event."},"startedAt":{"type":"string","format":"date-time","description":"When this event started."},"status":{"type":"string","enum":["running","completed","failed","skipped"],"description":"The status of the event."},"childExecutionId":{"type":"string","nullable":true,"description":"The child execution identifier."},"toolType":{"type":"string","description":"The type of tool called."},"type":{"type":"string","enum":["tool-call"],"description":"The event subtype represented by this payload."}},"required":["creditsUsed","endedAt","id","label","output","startedAt","status","childExecutionId","toolType","type"]}]},"description":"The events that occurred during this squad execution."},"origin":{"anyOf":[{"type":"object","properties":{"apiKeyId":{"type":"string","description":"The API key identifier."},"type":{"type":"string","enum":["api"],"description":"The execution origin subtype represented by this payload."}},"required":["apiKeyId","type"]},{"type":"object","properties":{"chatMessageId":{"type":"string","description":"The chat message identifier."},"retryOfExecutionId":{"type":"string","description":"The execution identifier of the prior retry attempt."},"type":{"type":"string","enum":["chat-message"],"description":"The execution origin subtype represented by this payload."}},"required":["chatMessageId","type"]},{"type":"object","properties":{"agentId":{"type":"string","description":"The agent identifier."},"type":{"type":"string","enum":["delegation"],"description":"The execution origin subtype represented by this payload."}},"required":["agentId","type"]},{"type":"object","properties":{"type":{"type":"string","enum":["agentic-execution-node"],"description":"The execution origin subtype represented by this payload."},"workflowNodeId":{"type":"string","description":"The workflow node identifier."}},"required":["type","workflowNodeId"]},{"type":"object","properties":{"event":{"type":"string","enum":["comment-created"],"description":"The source event type."},"externalEventId":{"type":"string","description":"The external event identifier."},"source":{"type":"string","enum":["instagram"],"description":"The source event provider."},"triggerId":{"type":"string","description":"The trigger identifier."},"type":{"type":"string","enum":["trigger"],"description":"The execution origin subtype represented by this payload."}},"required":["event","externalEventId","source","triggerId","type"]}],"description":"The origin of this squad execution."},"squadId":{"type":"string","description":"The squad identifier."},"type":{"type":"string","enum":["squad-execution"],"description":"The execution detail subtype represented by this payload."}},"required":["input","output","agentId","events","origin","squadId","type"]},{"type":"object","properties":{"input":{"type":"object","additionalProperties":{"nullable":true},"description":"The input data for this execution."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this execution."},"events":{"type":"array","items":{"type":"object","properties":{"creditsUsed":{"type":"number","minimum":0,"description":"The number of credits used by this event."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this event ended."},"id":{"type":"string","description":"The event identifier."},"input":{"anyOf":[{"nullable":true},{"type":"object","properties":{}}],"description":"The input data for this event."},"label":{"type":"string","minLength":3,"maxLength":50,"description":"The label for this event."},"llmUsages":{"type":"array","items":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The input token count reported by the LLM provider."},"model":{"type":"string","description":"The model key used for this LLM usage."},"outputTokens":{"type":"integer","nullable":true,"minimum":0,"description":"The output token count reported by the LLM provider."},"provider":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The provider ID associated with the LLM usage, when one exists."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The display name of the provider associated with the LLM usage."}},"required":["id","name"],"description":"The provider metadata associated with this LLM usage."}},"required":["inputTokens","model","outputTokens","provider"]},"description":"The custom-provider LLM usages recorded for this event."},"output":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"The output data for this event."},"startedAt":{"type":"string","format":"date-time","description":"When this event started."},"status":{"type":"string","enum":["running","completed","failed","skipped"],"description":"The status of the event."},"childExecutionId":{"type":"string","nullable":true,"description":"The child execution identifier."},"nodeType":{"type":"string","description":"The type of workflow node."},"type":{"type":"string","enum":["workflow-node"],"description":"The event subtype represented by this payload."},"workflowNodeId":{"type":"string","description":"The workflow node identifier."}},"required":["creditsUsed","endedAt","id","label","output","startedAt","status","childExecutionId","nodeType","type","workflowNodeId"]},"description":"The events that occurred during this workflow execution."},"origin":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["webhook-request"],"description":"The execution origin subtype represented by this payload."},"workflowTriggerId":{"type":"string","description":"The workflow trigger identifier."}},"required":["type","workflowTriggerId"]},{"type":"object","properties":{"type":{"type":"string","enum":["agent-tool-request"],"description":"The execution origin subtype represented by this payload."},"workflowTriggerId":{"type":"string","description":"The workflow trigger identifier."}},"required":["type","workflowTriggerId"]},{"type":"object","properties":{"event":{"type":"string","enum":["comment-created"],"description":"The source event type."},"externalEventId":{"type":"string","description":"The external event identifier."},"source":{"type":"string","enum":["instagram"],"description":"The source event provider."},"triggerId":{"type":"string","description":"The trigger identifier."},"type":{"type":"string","enum":["trigger"],"description":"The execution origin subtype represented by this payload."}},"required":["event","externalEventId","source","triggerId","type"]}],"description":"The origin of this workflow execution."},"type":{"type":"string","enum":["workflow-execution"],"description":"The execution detail subtype represented by this payload."},"workflowId":{"type":"string","description":"The workflow identifier."},"workflowImplementationId":{"type":"string","description":"The workflow implementation identifier."}},"required":["input","output","events","origin","type","workflowId","workflowImplementationId"]}],"description":"The execution detail containing type-specific information."},"endedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this execution ended."},"isAgentic":{"type":"boolean","description":"Whether this execution is agentic."},"isFailedAttempt":{"type":"boolean","description":"Whether this execution belongs to a failed retry attempt."},"isPurged":{"type":"boolean","description":"Whether this execution has been purged."},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"The parent execution ID of this execution."},"responderId":{"type":"string","description":"The responder ID of this execution."},"startedAt":{"type":"string","format":"date-time","description":"When this execution started."},"status":{"type":"string","enum":["running","completed","failed","cancelled"],"description":"The status of the execution."},"workspaceId":{"type":"string","description":"The workspace ID of this execution."}},"required":["createdAt","id","updatedAt","creditsUsed","detail","endedAt","isAgentic","isFailedAttempt","isPurged","parentId","responderId","startedAt","status","workspaceId"]}},"required":["attachmentsUrls","content","execution"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## GET /api/v1/agents/{id}

> Retrieves an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{id}":{"get":{"description":"Retrieves an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"Retrieves an agent.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this agent was last executed."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice to use for audio responses. Null when disabled for the agent."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the agent."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","codeRuntime","internalName","iterations","lastExecutedAt","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","superIdentityId","temperature","timezone","toolCount","voiceId","workspaceId"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## DELETE /api/v1/agents/{id}

> Removes an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{id}":{"delete":{"description":"Removes an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"The agent was removed.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"An informative message for a call that has no effective result to be returned."}},"required":["message"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"412":{"description":"Precondition failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## PATCH /api/v1/agents/{id}

> Updates an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{id}":{"patch":{"description":"Updates an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice for audio responses. Null to disable."}}}}}},"responses":{"200":{"description":"The agent was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"isRemoved":{"type":"boolean"},"referenceId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the original entity in production."},"updatedAt":{"type":"string","format":"date-time"},"versionId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"codeRuntime":{"type":"boolean","description":"Whether the agent should be able to execute JavaScript code using the Code Runtime tool."},"internalName":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The internal name of the agent. For internal use only."},"iterations":{"type":"number","minimum":2,"maximum":100,"description":"The number of iterations (steps) the agent can execute in a single execution."},"lastExecutedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this agent was last executed."},"llm":{"type":"string","enum":["claude-haiku-4-5","claude-opus-4-8","claude-opus-4-6","claude-opus-4-5","claude-sonnet-4-6","claude-sonnet-4-5","gpt-5.2","gpt-5.5","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.6-luna","gpt-5.6-sol","gpt-5.6-terra","gemini-2.5-flash","gemini-2.5-pro","gemini-3.5-flash","gemini-3-flash","gemini-3-pro","gemini-3.1-pro","kimi-k2.5","kimi-k2.6","grok-4.3","grok-4.5"],"description":"The LLM model key to use for the agent."},"llmProviderId":{"type":"string","nullable":true,"format":"uuid","description":"The id of the LLM provider to use for the agent."},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The name of the agent."},"picture":{"type":"string","nullable":true,"description":"The picture of the agent."},"planning":{"type":"boolean","description":"Whether the agent should plan before each execution."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"The main description of the agent's behavior."},"reasoningMode":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh",null],"description":"The reasoning mode to use for the agent. If null, reasoning will be disabled."},"role":{"type":"string","minLength":1,"maxLength":250,"description":"The role of the agent. Particularly useful to give other agents context of what the agent does."},"superIdentityId":{"type":"string","format":"uuid","description":"The super identity ID associated with the agent."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"The temperature to use for the agent. The lower the more deterministic. The higher the more creative."},"timezone":{"type":"string","nullable":true,"enum":["Africa/Cairo","Africa/Johannesburg","America/Chicago","America/Denver","America/Los_Angeles","America/New_York","America/Sao_Paulo","America/Manaus","Asia/Dubai","Asia/Kolkata","Asia/Shanghai","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Europe/Berlin","Europe/London","Europe/Moscow","Europe/Paris","Pacific/Auckland","Pacific/Auckland2","UTC","auto",null],"description":"The timezone to use for the agent. If null, no timezone will be used."},"toolCount":{"type":"integer","minimum":0,"description":"The number of tools currently associated with the agent."},"voiceId":{"type":"string","nullable":true,"format":"uuid","description":"The TTS voice to use for audio responses. Null when disabled for the agent."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace ID that owns the agent."}},"required":["createdAt","id","isRemoved","referenceId","updatedAt","versionId","codeRuntime","internalName","iterations","lastExecutedAt","llm","llmProviderId","name","picture","planning","prompt","reasoningMode","role","superIdentityId","temperature","timezone","toolCount","voiceId","workspaceId"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## DELETE /api/v1/agents/{agentId}/mcps/{mcpId}

> Detaches an MCP from an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{agentId}/mcps/{mcpId}":{"delete":{"description":"Detaches an MCP from an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"agentId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"mcpId","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"The MCP was removed from the agent.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"An informative message for a call that has no effective result to be returned."}},"required":["message"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent or MCP not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## DELETE /api/v1/agents/{agentId}/tools/{toolId}

> Detaches a tool from an agent.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/agents/{agentId}/tools/{toolId}":{"delete":{"description":"Detaches a tool from an agent.","tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"agentId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"toolId","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"The tool was removed from the agent.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"An informative message for a call that has no effective result to be returned."}},"required":["message"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Agent or tool not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```