Runtime

Agent lifecycle control (start, stop, pause, reload, health)

Get agent runtime status

get

Returns current status, uptime, and last boot/stop timestamps. Requires agent:manage scope (master keys always pass).

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 status

application/json

statusstring · enumOptionalPossible values:

last_boot_executionstring · date-time · nullableOptional

last_stop_executionstring · date-time · nullableOptional

uptime_total_secondsintegerOptional

current_uptimeintegerOptional

Seconds since last boot (0 if not running)

server_timestampintegerOptional

Server time in epoch milliseconds

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

get/agents/{id}/status

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

{
  "status": "created",
  "last_boot_execution": "2026-01-01T00:00:00.000Z",
  "last_stop_execution": "2026-01-01T00:00:00.000Z",
  "uptime_total_seconds": 1,
  "current_uptime": 1,
  "server_timestamp": 1
}

Start an agent

post

Boots the agent (or resumes from paused). Requires agent:manage scope. Charges 5 credits. Subject to subscription guards (max running agents, allowed channels).

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 started

application/json

successbooleanOptional

messagestringOptional

401

Unauthorized — Invalid or missing API key

application/json

402

Payment Required — Insufficient credits

application/json

403

Forbidden — Key lacks the required scope

application/json

post/agents/{id}/start

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

{
  "success": true,
  "message": "text",
  "data": {
    "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"
    },
    "previous_status": "text"
  }
}

Stop an agent

post

Stops the agent and accumulates uptime. Requires agent:manage scope. 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 stopped

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post/agents/{id}/stop

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

No content

Pause an agent

post

Pauses the agent without stopping the container. Requires agent:manage scope. 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 paused

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post/agents/{id}/pause

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

No content

Reload agent config

post

Hot-reloads the agent configuration without restarting. Agent must be in running state. Requires agent:manage scope. Charges 1 credit.

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

Config reloaded

application/json

messagestringOptional

400

Agent is not running

401

Unauthorized — Invalid or missing API key

application/json

402

Payment Required — Insufficient credits

application/json

403

Forbidden — Key lacks the required scope

application/json

post/agents/{id}/reload

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

{
  "message": "text",
  "data": {
    "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"
    }
  }
}

Agent health check

get

Returns health status for a running agent. Requires agent:manage scope.

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 is healthy

application/json

successbooleanOptional

messagestringOptional

agent_statusstringOptional

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

503

Agent container not running

get/agents/{id}/health

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

{
  "success": true,
  "message": "text",
  "agent_status": "text",
  "health": {
    "status": "text",
    "launcher": "text",
    "gateway": "text",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}