Agents API

All agent endpoints require the agent runtime to be initialized. The API server runs on port 2138 by default when started with eliza start. In dev mode (bun run dev), the API splits to port 31337 while the UI stays on 2138. Override with ELIZA_API_PORT (dev API) or ELIZA_PORT (server-only / UI). All paths are prefixed with /api/. When ELIZA_API_TOKEN is set, include it as a Bearer token in the Authorization header.

Endpoints

GET /api/agents

List the running agent(s). The app runs a single agent; the response wraps it in an agents array for compatibility with multi-agent callers and health probes.

Response

{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Eliza",
      "status": "running"
    }
  ]
}

POST /api/agent/start

Start the agent. Sets the agent state to running, records the start timestamp, and detects the active model provider.

Response

{
  "status": {
    "state": "running",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "uptime": 0,
    "startedAt": 1718000000000
  }
}

POST /api/agent/stop

Stop the agent and disable autonomy. Sets the agent state to stopped and clears uptime tracking.

Response

{
  "status": {
    "state": "stopped",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "startedAt": 1718000000000,
    "uptime": 34200000
  }
}

POST /api/agent/pause

Pause the agent while keeping uptime intact. Disables autonomy but preserves the startedAt timestamp and model info.

Response

{
  "status": {
    "state": "paused",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "uptime": 34200000,
    "startedAt": 1718000000000
  }
}

POST /api/agent/resume

Resume a paused agent and re-enable autonomy. The first tick fires immediately.

Response

{
  "status": {
    "state": "running",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "uptime": 34200000,
    "startedAt": 1718000000000
  }
}

GET /api/agent/autonomy

Check whether autonomous operation is currently enabled.

Response

{
  "enabled": true
}

POST /api/agent/autonomy

Enable or disable autonomous operation.

Request Body

Response

{
  "enabled": true
}

POST /api/agent/restart

Restart the agent runtime. Returns 409 if a restart is already in progress and 501 if restart is not supported in the current mode.

Response

{
  "status": {
    "state": "running",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "startedAt": 1718000000000
  }
}

POST /api/agent/reset

Wipe memory, onboarding config, cloud secrets, and return to onboarding state. Stops the runtime, deletes the PGlite database directory (with safety checks), clears persisted onboarding and cloud credentials, and resets server state. GGUF models and the state directory itself are preserved.

This is a sensitive endpoint with stricter authorization:

• If ELIZA_API_TOKEN is configured, the request must include it as a Bearer token.
• If no token is configured, the request is only allowed from loopback addresses (localhost). Non-loopback requests without a token return 403.

Response

{
  "ok": true
}

POST /api/agent/export

Export the entire agent as a password-encrypted .eliza-agent binary file. The agent must be running. Returns an application/octet-stream file download.

Request

Response

Binary file download with Content-Disposition: attachment; filename="agentname-YYYY-MM-DDTHH-MM-SS.eliza-agent".

GET /api/agent/export/estimate

Estimate the export file size before downloading. The agent must be running.

Response

{
  "estimatedBytes": 1048576,
  "estimatedMb": 1.0
}

POST /api/agent/import

Import an agent from a password-encrypted .eliza-agent file. The request body is a binary envelope: [4 bytes password length (big-endian uint32)][password bytes][file data]. Maximum import size is 512 MB.

Request

Raw binary body — not JSON. The first 4 bytes encode the password length as a big-endian unsigned 32-bit integer, followed by the UTF-8 password, followed by the file data.

Response

{
  "ok": true
}

GET /api/agent/events

Get buffered agent events including actions, thoughts, and status changes. Supports long-polling via the since parameter to receive only new events.

Query Parameters

Response

{
  "events": [],
  "latestEventId": null,
  "totalBuffered": 0,
  "replayed": true
}

GET /api/agent/self-status

Get a structured summary of the agent's current state, capabilities, wallet status, active plugins, and an optional awareness registry snapshot. Designed for programmatic consumers and the agent's own self-awareness system.

Response

{
  "generatedAt": "2026-04-09T12:00:00.000Z",
  "state": "running",
  "agentName": "Eliza",
  "model": "anthropic/claude-sonnet-4.6",
  "provider": "anthropic",
  "automationMode": "connectors-only",
  "tradePermissionMode": "ask",
  "shellEnabled": true,
  "wallet": {
    "hasWallet": true,
    "hasEvm": true,
    "hasSolana": false,
    "evmAddress": "0x1234...abcd",
    "evmAddressShort": "0x1234...abcd",
    "solanaAddress": null,
    "solanaAddressShort": null,
    "localSignerAvailable": true,
    "managedBscRpcReady": true
  },
  "plugins": {
    "totalActive": 12,
    "active": ["..."],
    "aiProviders": ["@elizaos/plugin-anthropic"],
    "connectors": ["@elizaos/plugin-discord"]
  },
  "capabilities": {
    "canTrade": true,
    "canLocalTrade": true,
    "canAutoTrade": false,
    "canUseBrowser": false,
    "canUseComputer": false,
    "canRunTerminal": true,
    "canInstallPlugins": true,
    "canConfigurePlugins": true,
    "canConfigureConnectors": true
  },
  "registrySummary": "Runtime: running | Wallet: EVM ready | Plugins: 12 active | Cloud: disconnected"
}

wallet fields

plugins fields

capabilities fields

Common Error Codes