# Agents
CRUD operations on AI agents
## List user's agents
> Returns a paginated list of all agents belonging to the API key owner.\
> Works with any API key type (master or agent).
```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/agents":{"get":{"tags":["Agents"],"summary":"List user's agents","description":"Returns a paginated list of all agents belonging to the API key owner.\nWorks with any API key type (master or agent).\n","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","default":100}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Paginated list of agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}}
```
## Create a new agent
> Creates a new AI agent. Requires a \*\*master key\*\*.\
> Charges \*\*10 credits\*\*.
```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"AgentSettingsInput":{"type":"object","description":"Input schema for creating or updating an agent","properties":{"name":{"type":"string","maxLength":255},"llm_provider_name":{"type":"string"},"llm_provider_model":{"type":"string"},"bio":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000}},"knowledge":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":5000}},"channels":{"type":"array","maxItems":10,"items":{"type":"string"}},"model_provider":{"type":"string"},"settings":{"type":"object","properties":{"model":{"type":"string","maxLength":255},"thinking":{"type":"string","enum":["off","low","medium","high"]},"extra_instructions":{"type":"string","maxLength":10000},"secrets":{"type":"object","description":"Key-value map. Send null or \"\" to delete a secret; omit the key to keep it.","additionalProperties":{"type":"string","nullable":true}},"trusted_proxies":{"type":"array","maxItems":10,"items":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer","minimum":1,"maximum":10080},"POST_INTERVAL_MAX":{"type":"integer","minimum":1,"maximum":10080},"TWITTER_POLL_INTERVAL":{"type":"integer","minimum":10,"maximum":86400},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer","minimum":1,"maximum":100},"ACTION_INTERVAL":{"type":"integer","minimum":1,"maximum":10080}}},"auto_generation_prompt":{"type":"string","maxLength":10000},"auto_enhancement_prompt":{"type":"string","maxLength":10000},"framework_id":{"type":"string","format":"uuid"},"region_id":{"type":"string","format":"uuid"},"ram_id":{"type":"string","format":"uuid"},"disk_id":{"type":"string","format":"uuid"},"gpu_id":{"type":"string","format":"uuid"},"cpu_id":{"type":"string","format":"uuid"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents":{"post":{"tags":["Agents"],"summary":"Create a new agent","description":"Creates a new AI agent. Requires a **master key**.\nCharges **10 credits**.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSettingsInput"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"422":{"description":"Validation error"}}}}}}
```
## Show agent details
> Returns full details for a specific agent.\
> \- \*\*Master key\*\*: can access any of the user's agents.\
> \- \*\*Agent key\*\*: requires \`agent:read\` scope (always included). Can only access its linked agent.
```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}":{"get":{"tags":["Agents"],"summary":"Show agent details","description":"Returns full details for a specific agent.\n- **Master key**: can access any of the user's agents.\n- **Agent key**: requires `agent:read` scope (always included). Can only access its linked agent.\n","responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Agent key does not have access to this agent"},"404":{"description":"Agent not found"}}}}}}
```
## Update an agent
> Updates an existing agent (PATCH semantics — only provided fields are changed).\
> Requires a \*\*master key\*\*. Charges \*\*10 credits\*\*.\
> \
> \*\*Secrets use PATCH semantics\*\*: sending \`null\` or \`""\` for a secret key deletes it;\
> omitting the \`secrets\` key entirely preserves all existing secrets.
```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"AgentSettingsInput":{"type":"object","description":"Input schema for creating or updating an agent","properties":{"name":{"type":"string","maxLength":255},"llm_provider_name":{"type":"string"},"llm_provider_model":{"type":"string"},"bio":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000}},"knowledge":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":5000}},"channels":{"type":"array","maxItems":10,"items":{"type":"string"}},"model_provider":{"type":"string"},"settings":{"type":"object","properties":{"model":{"type":"string","maxLength":255},"thinking":{"type":"string","enum":["off","low","medium","high"]},"extra_instructions":{"type":"string","maxLength":10000},"secrets":{"type":"object","description":"Key-value map. Send null or \"\" to delete a secret; omit the key to keep it.","additionalProperties":{"type":"string","nullable":true}},"trusted_proxies":{"type":"array","maxItems":10,"items":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer","minimum":1,"maximum":10080},"POST_INTERVAL_MAX":{"type":"integer","minimum":1,"maximum":10080},"TWITTER_POLL_INTERVAL":{"type":"integer","minimum":10,"maximum":86400},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer","minimum":1,"maximum":100},"ACTION_INTERVAL":{"type":"integer","minimum":1,"maximum":10080}}},"auto_generation_prompt":{"type":"string","maxLength":10000},"auto_enhancement_prompt":{"type":"string","maxLength":10000},"framework_id":{"type":"string","format":"uuid"},"region_id":{"type":"string","format":"uuid"},"ram_id":{"type":"string","format":"uuid"},"disk_id":{"type":"string","format":"uuid"},"gpu_id":{"type":"string","format":"uuid"},"cpu_id":{"type":"string","format":"uuid"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}":{"put":{"tags":["Agents"],"summary":"Update an agent","description":"Updates an existing agent (PATCH semantics — only provided fields are changed).\nRequires a **master key**. Charges **10 credits**.\n\n**Secrets use PATCH semantics**: sending `null` or `\"\"` for a secret key deletes it;\nomitting the `secrets` key entirely preserves all existing secrets.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSettingsInput"}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"404":{"description":"Agent not found"}}}}}}
```
## Delete an agent
> Deletes an agent. Stops it first if running/paused.\
> Cascades to related API keys and runtime sessions.\
> Requires a \*\*master key\*\*. No credit charge.
```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}":{"delete":{"tags":["Agents"],"summary":"Delete an agent","description":"Deletes an agent. Stops it first if running/paused.\nCascades to related API keys and runtime sessions.\nRequires a **master key**. No credit charge.\n","responses":{"200":{"description":"Agent deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"404":{"description":"Agent not found"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.guayaba.run/documentation/api-reference/agents.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.