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

# 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).<br>

```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\*\*.<br>

```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.<br>

```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.<br>

```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.<br>

```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"}}}}}}
```
