Agents
CRUD operations on AI agents
Returns a paginated list of all agents belonging to the API key owner. Works with any API key type (master or agent).
Authorizations
AuthorizationstringRequired
API key sent as Bearer token. Two types:
- Master key (
g_master_...): full access to all agents and endpoints. - Agent key (
g_agent_...): scoped to a single agent with specific permissions.
Query parameters
per_pageintegerOptionalDefault:
100pageintegerOptionalDefault:
1Responses
200
Paginated list of agents
application/json
current_pageintegerOptional
last_pageintegerOptional
per_pageintegerOptional
totalintegerOptional
401
Unauthorized — Invalid or missing API key
application/json
403
Forbidden — Active subscription required
application/json
get/agents
GET /api/v1/agents HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"status": "created",
"settings": {
"model": "openai/gpt-4.1",
"thinking": "medium",
"extra_instructions": "text",
"trusted_proxies": [
"text"
],
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"secrets_configured": {
"TELEGRAM_BOT_TOKEN": true,
"OPENROUTER_API_KEY": true
},
"face_image_path": "text",
"face_image_generation_prompt": "text",
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"is_featured": true,
"last_boot_execution": "2026-01-01T00:00:00.000Z",
"last_stop_execution": "2026-01-01T00:00:00.000Z",
"uptime_total_seconds": 1,
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"framework": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "openclaw",
"name": "OpenClaw",
"description": "text",
"icon": "text",
"available": true,
"tag": "text"
},
"hardware_config": {
"region": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "eu-central-1",
"label": "EU (Frankfurt)",
"city": "Frankfurt",
"coords": {
"lat": 1,
"lng": 1
},
"available": true
},
"ram": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"disk": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"gpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"cpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
}
},
"client_links": [
{
"name": "text",
"link": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"current_page": 1,
"last_page": 1,
"per_page": 1,
"total": 1
}Creates a new AI agent. Requires a master key. Charges 10 credits.
Authorizations
AuthorizationstringRequired
API key sent as Bearer token. Two types:
- Master key (
g_master_...): full access to all agents and endpoints. - Agent key (
g_agent_...): scoped to a single agent with specific permissions.
Body
Input schema for creating or updating an agent
namestring · max: 255Optional
llm_provider_namestringOptionalExample:
openrouterllm_provider_modelstringOptionalExample:
openai/gpt-4.1biostring[] · max: 50Optional
knowledgestring[] · max: 100Optional
channelsstring[] · max: 10Optional
model_providerstringOptional
auto_generation_promptstring · max: 10000Optional
auto_enhancement_promptstring · max: 10000Optional
framework_idstring · uuidOptional
region_idstring · uuidOptional
ram_idstring · uuidOptional
disk_idstring · uuidOptional
gpu_idstring · uuidOptional
cpu_idstring · uuidOptional
Responses
201
Agent created
application/json
successbooleanOptional
messagestringOptionalExample:
Agent created successfully401
Unauthorized — Invalid or missing API key
application/json
402
Payment Required — Insufficient credits
application/json
403
Forbidden — Requires a master API key
application/json
422
Validation error
post/agents
POST /api/v1/agents HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 850
{
"name": "text",
"llm_provider_name": "openrouter",
"llm_provider_model": "openai/gpt-4.1",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"settings": {
"model": "text",
"thinking": "off",
"extra_instructions": "text",
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"trusted_proxies": [
"text"
],
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"region_id": "123e4567-e89b-12d3-a456-426614174000",
"ram_id": "123e4567-e89b-12d3-a456-426614174000",
"disk_id": "123e4567-e89b-12d3-a456-426614174000",
"gpu_id": "123e4567-e89b-12d3-a456-426614174000",
"cpu_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"success": true,
"message": "Agent created successfully",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"status": "created",
"settings": {
"model": "openai/gpt-4.1",
"thinking": "medium",
"extra_instructions": "text",
"trusted_proxies": [
"text"
],
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"secrets_configured": {
"TELEGRAM_BOT_TOKEN": true,
"OPENROUTER_API_KEY": true
},
"face_image_path": "text",
"face_image_generation_prompt": "text",
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"is_featured": true,
"last_boot_execution": "2026-01-01T00:00:00.000Z",
"last_stop_execution": "2026-01-01T00:00:00.000Z",
"uptime_total_seconds": 1,
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"framework": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "openclaw",
"name": "OpenClaw",
"description": "text",
"icon": "text",
"available": true,
"tag": "text"
},
"hardware_config": {
"region": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "eu-central-1",
"label": "EU (Frankfurt)",
"city": "Frankfurt",
"coords": {
"lat": 1,
"lng": 1
},
"available": true
},
"ram": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"disk": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"gpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"cpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
}
},
"client_links": [
{
"name": "text",
"link": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
}Returns full details for a specific agent.
Master key: can access any of the user's agents.
Agent key: requires
agent:readscope (always included). Can only access its linked agent.
Authorizations
AuthorizationstringRequired
API key sent as Bearer token. Two types:
- Master key (
g_master_...): full access to all agents and endpoints. - Agent key (
g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Responses
200
Agent details
application/json
401
Unauthorized — Invalid or missing API key
application/json
403
Agent key does not have access to this agent
404
Agent not found
get/agents/{id}
GET /api/v1/agents/{id} HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"agent": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"status": "created",
"settings": {
"model": "openai/gpt-4.1",
"thinking": "medium",
"extra_instructions": "text",
"trusted_proxies": [
"text"
],
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"secrets_configured": {
"TELEGRAM_BOT_TOKEN": true,
"OPENROUTER_API_KEY": true
},
"face_image_path": "text",
"face_image_generation_prompt": "text",
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"is_featured": true,
"last_boot_execution": "2026-01-01T00:00:00.000Z",
"last_stop_execution": "2026-01-01T00:00:00.000Z",
"uptime_total_seconds": 1,
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"framework": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "openclaw",
"name": "OpenClaw",
"description": "text",
"icon": "text",
"available": true,
"tag": "text"
},
"hardware_config": {
"region": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "eu-central-1",
"label": "EU (Frankfurt)",
"city": "Frankfurt",
"coords": {
"lat": 1,
"lng": 1
},
"available": true
},
"ram": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"disk": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"gpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"cpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
}
},
"client_links": [
{
"name": "text",
"link": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
}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.
Authorizations
AuthorizationstringRequired
API key sent as Bearer token. Two types:
- Master key (
g_master_...): full access to all agents and endpoints. - Agent key (
g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
Input schema for creating or updating an agent
namestring · max: 255Optional
llm_provider_namestringOptionalExample:
openrouterllm_provider_modelstringOptionalExample:
openai/gpt-4.1biostring[] · max: 50Optional
knowledgestring[] · max: 100Optional
channelsstring[] · max: 10Optional
model_providerstringOptional
auto_generation_promptstring · max: 10000Optional
auto_enhancement_promptstring · max: 10000Optional
framework_idstring · uuidOptional
region_idstring · uuidOptional
ram_idstring · uuidOptional
disk_idstring · uuidOptional
gpu_idstring · uuidOptional
cpu_idstring · uuidOptional
Responses
200
Agent updated
application/json
successbooleanOptional
messagestringOptional
401
Unauthorized — Invalid or missing API key
application/json
402
Payment Required — Insufficient credits
application/json
403
Forbidden — Requires a master API key
application/json
404
Agent not found
put/agents/{id}
PUT /api/v1/agents/{id} HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 850
{
"name": "text",
"llm_provider_name": "openrouter",
"llm_provider_model": "openai/gpt-4.1",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"settings": {
"model": "text",
"thinking": "off",
"extra_instructions": "text",
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"trusted_proxies": [
"text"
],
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"region_id": "123e4567-e89b-12d3-a456-426614174000",
"ram_id": "123e4567-e89b-12d3-a456-426614174000",
"disk_id": "123e4567-e89b-12d3-a456-426614174000",
"gpu_id": "123e4567-e89b-12d3-a456-426614174000",
"cpu_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"success": true,
"message": "text",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"bio": [
"text"
],
"knowledge": [
"text"
],
"channels": [
"text"
],
"model_provider": "text",
"status": "created",
"settings": {
"model": "openai/gpt-4.1",
"thinking": "medium",
"extra_instructions": "text",
"trusted_proxies": [
"text"
],
"secrets": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"POST_IMMEDIATELY": true,
"POST_INTERVAL_MIN": 1,
"POST_INTERVAL_MAX": 1,
"TWITTER_POLL_INTERVAL": 1,
"ACTION_TIMELINE_TYPE": "following",
"MAX_ACTIONS_PROCESSING": 1,
"ACTION_INTERVAL": 1
},
"secrets_configured": {
"TELEGRAM_BOT_TOKEN": true,
"OPENROUTER_API_KEY": true
},
"face_image_path": "text",
"face_image_generation_prompt": "text",
"auto_generation_prompt": "text",
"auto_enhancement_prompt": "text",
"is_featured": true,
"last_boot_execution": "2026-01-01T00:00:00.000Z",
"last_stop_execution": "2026-01-01T00:00:00.000Z",
"uptime_total_seconds": 1,
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"framework_id": "123e4567-e89b-12d3-a456-426614174000",
"framework": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "openclaw",
"name": "OpenClaw",
"description": "text",
"icon": "text",
"available": true,
"tag": "text"
},
"hardware_config": {
"region": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "eu-central-1",
"label": "EU (Frankfurt)",
"city": "Frankfurt",
"coords": {
"lat": 1,
"lng": 1
},
"available": true
},
"ram": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"disk": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"gpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
},
"cpu": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"label": "text",
"description": "text",
"available": true
}
},
"client_links": [
{
"name": "text",
"link": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
}Deletes an agent. Stops it first if running/paused. Cascades to related API keys and runtime sessions. Requires a master key. No credit charge.
Authorizations
AuthorizationstringRequired
API key sent as Bearer token. Two types:
- Master key (
g_master_...): full access to all agents and endpoints. - Agent key (
g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Responses
200
Agent deleted
application/json
successbooleanOptional
messagestringOptionalExample:
Agent deleted successfully401
Unauthorized — Invalid or missing API key
application/json
403
Forbidden — Requires a master API key
application/json
404
Agent not found
delete/agents/{id}
DELETE /api/v1/agents/{id} HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true,
"message": "Agent deleted successfully"
}Last updated