Agents

CRUD operations on AI agents

List user's agents

get

Returns a paginated list of all agents belonging to the API key owner. Works with any API key type (master or agent).

Authorizations

PublicApiKey

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: 100

pageintegerOptionalDefault: 1

Responses

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

HTTPcURLJavaScriptPython

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-06-04T13:11:32.115Z",
      "last_stop_execution": "2026-06-04T13:11:32.115Z",
      "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-06-04T13:11:32.115Z",
      "updated_at": "2026-06-04T13:11:32.115Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 1,
  "total": 1
}

Create a new agent

post

Creates a new AI agent. Requires a master key. Charges 10 credits.

Authorizations

PublicApiKey

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

application/json

Input schema for creating or updating an agent

namestring · max: 255Optional

llm_provider_namestringOptionalExample: openrouter

llm_provider_modelstringOptionalExample: openai/gpt-4.1

biostring[] · 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

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

422

Validation error

post

/agents

HTTPcURLJavaScriptPython

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-06-04T13:11:32.115Z",
    "last_stop_execution": "2026-06-04T13:11:32.115Z",
    "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-06-04T13:11:32.115Z",
    "updated_at": "2026-06-04T13:11:32.115Z"
  }
}

Show agent details

get

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.

Authorizations

PublicApiKey

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}

HTTPcURLJavaScriptPython

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-06-04T13:11:32.115Z",
    "last_stop_execution": "2026-06-04T13:11:32.115Z",
    "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-06-04T13:11:32.115Z",
    "updated_at": "2026-06-04T13:11:32.115Z"
  }
}

Update an agent

put

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

PublicApiKey

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

application/json

Input schema for creating or updating an agent

namestring · max: 255Optional

llm_provider_namestringOptionalExample: openrouter

llm_provider_modelstringOptionalExample: openai/gpt-4.1

biostring[] · 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}

HTTPcURLJavaScriptPython

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-06-04T13:11:32.115Z",
    "last_stop_execution": "2026-06-04T13:11:32.115Z",
    "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-06-04T13:11:32.115Z",
    "updated_at": "2026-06-04T13:11:32.115Z"
  }
}

Delete an agent

delete

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

PublicApiKey

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 successfully

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Requires a master API key

application/json

404

Agent not found

delete

/agents/{id}

HTTPcURLJavaScriptPython

DELETE /api/v1/agents/{id} HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "message": "Agent deleted successfully"
}