elizaOS
Core Concepts/Communication & Events

REST API Reference

Complete guide to ElizaOS REST API endpoints and usage

The ElizaOS server provides a comprehensive REST API for interacting with agents, managing messages, and accessing system functionality. All API endpoints are mounted under /api with proper authentication and validation.

Authentication

API endpoints can be secured with an optional API key:

# Set authentication token
export ELIZA_SERVER_AUTH_TOKEN=your-secret-token

# Make authenticated requests
curl -H "X-API-KEY: your-secret-token" \
  http://localhost:3000/api/agents

API Structure

The API is organized into domain-specific routers:

  • /api/agents - Agent management and interactions
  • /api/messaging - Message handling and channels
  • /api/media - File uploads and media serving
  • /api/memory - Memory management and retrieval
  • /api/audio - Audio processing and transcription
  • /api/server - Runtime and server management
  • /api/system - System configuration and health
  • /api/tee - TEE (Trusted Execution Environment) operations

Request/Response Format

All API endpoints follow consistent patterns:

Request Headers

Content-Type: application/json
X-API-KEY: your-secret-token (if auth enabled)
Accept: application/json

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional error details"
  }
}

Agent Management

List Agents

GET /api/agents

Returns a list of all agents with minimal details, sorted by status and name.

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Alice",
        "characterName": "Alice",
        "bio": "A helpful assistant",
        "status": "active"
      }
    ]
  }
}

Get Agent Details

GET /api/agents/{agentId}

Returns complete agent configuration including character details.

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Alice",
    "bio": ["A helpful assistant"],
    "lore": ["Background information"],
    "settings": {
      "secrets": {},
      "voice": {}
    },
    "status": "active"
  }
}

Create Agent

POST /api/agents
Content-Type: application/json

Create a new agent from character configuration. Supports three input methods:

Method 1: Character JSON

{
  "characterJson": {
    "name": "Bob",
    "bio": ["A specialized assistant"],
    "lore": ["Background story"],
    "settings": {
      "secrets": {
        "openai_api_key": "sk-..."
      },
      "voice": {
        "model": "en_US-hfc_female-medium"
      }
    }
  }
}

Method 2: Character Path

{
  "characterPath": "/path/to/character.json"
}

Method 3: Agent Object

{
  "agent": {
    "name": "Bob",
    "bio": ["A specialized assistant"]
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "character": {
      "name": "Bob",
      "bio": ["A specialized assistant"]
    }
  }
}

Update Agent

PATCH /api/agents/{agentId}
Content-Type: application/json

{
  "name": "Bob Updated",
  "bio": ["An updated assistant"],
  "settings": {
    "secrets": {
      "openai_api_key": "sk-new-key"
    }
  }
}

Updates agent configuration. Automatically encrypts secrets and restarts active agents.

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Bob Updated",
    "status": "active"
  }
}

Delete Agent

DELETE /api/agents/{agentId}

Permanently deletes an agent. Automatically stops the agent if running.

Response:

HTTP/1.1 204 No Content

Agent Lifecycle

Start Agent

POST /api/agents/{agentId}/start

Stop Agent

POST /api/agents/{agentId}/stop

Restart Agent

POST /api/agents/{agentId}/restart

Agent Logs

Get Agent Logs

GET /api/agents/{agentId}/logs?level=info&limit=100

Query Parameters:

  • level - Log level filter (debug, info, warn, error)
  • limit - Maximum number of log entries
  • since - Timestamp to get logs since

Agent Worlds

List Agent Worlds

GET /api/agents/{agentId}/worlds

Get World Details

GET /api/agents/{agentId}/worlds/{worldId}

Messaging

Submit Message

Submit a message to the central message bus for agent processing.

POST /api/messaging/submit
Content-Type: application/json

{
  "channel_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_id": "00000000-0000-0000-0000-000000000000",
  "author_id": "550e8400-e29b-41d4-a716-446655440001",
  "content": "Hello, how can you help me?",
  "source_type": "agent_response",
  "raw_message": {
    "text": "Hello, how can you help me?",
    "thought": "User is asking for help",
    "actions": ["respond"]
  },
  "metadata": {
    "agentName": "Alice",
    "attachments": []
  },
  "in_reply_to_message_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "authorId": "550e8400-e29b-41d4-a716-446655440001",
    "content": "Hello, how can you help me?",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Ingest External Message

Ingest messages from external platforms into the central message bus.

POST /api/messaging/ingest-external
Content-Type: application/json

{
  "channel_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_id": "00000000-0000-0000-0000-000000000000",
  "author_id": "550e8400-e29b-41d4-a716-446655440001",
  "content": "Hello from Discord!",
  "source_type": "discord",
  "source_id": "discord_message_123",
  "author_display_name": "User123",
  "raw_message": {
    "id": "discord_message_123",
    "content": "Hello from Discord!",
    "timestamp": "2024-01-01T00:00:00.000Z"
  },
  "metadata": {
    "platform": "discord",
    "guild_id": "discord_guild_456"
  }
}

Response:

{
  "success": true,
  "message": "Message ingested and published to bus",
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440002"
  }
}

Complete Message

Notify that message processing is complete.

POST /api/messaging/complete
Content-Type: application/json

{
  "channel_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_id": "00000000-0000-0000-0000-000000000000"
}

Channel Management

List Channels

GET /api/messaging/central-servers/{serverId}/channels

Create Channel

POST /api/messaging/central-channels
Content-Type: application/json

{
  "messageServerId": "00000000-0000-0000-0000-000000000000",
  "name": "General Chat",
  "type": "GROUP",
  "sourceType": "api_created",
  "participantIds": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ]
}

Get Channel Details

GET /api/messaging/central-channels/{channelId}/details

Get Channel Messages

GET /api/messaging/central-channels/{channelId}/messages?limit=50&before=2024-01-01T00:00:00.000Z

Update Channel

PATCH /api/messaging/central-channels/{channelId}
Content-Type: application/json

{
  "name": "Updated Channel Name",
  "participantCentralUserIds": [
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Delete Channel

DELETE /api/messaging/central-channels/{channelId}

Clear Channel Messages

DELETE /api/messaging/central-channels/{channelId}/messages

Message Server Management

List Servers

GET /api/messaging/central-servers

Create Server

POST /api/messaging/central-servers
Content-Type: application/json

{
  "name": "My Server",
  "sourceType": "custom",
  "metadata": {
    "description": "Custom server for testing"
  }
}

Get Server Details

GET /api/messaging/central-servers/{serverId}

Update Server

PATCH /api/messaging/central-servers/{serverId}
Content-Type: application/json

{
  "name": "Updated Server Name",
  "metadata": {
    "description": "Updated description"
  }
}

Delete Server

DELETE /api/messaging/central-servers/{serverId}

Agent-Server Association

Add Agent to Server

POST /api/messaging/agents/{agentId}/servers/{serverId}

Remove Agent from Server

DELETE /api/messaging/agents/{agentId}/servers/{serverId}

Get Agent's Servers

GET /api/messaging/agents/{agentId}/servers

Media Management

Upload File

POST /api/media/upload
Content-Type: multipart/form-data

{
  "file": <file_data>,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "roomId": "550e8400-e29b-41d4-a716-446655440001"
}

Response:

{
  "success": true,
  "data": {
    "url": "/media/uploads/agents/550e8400-e29b-41d4-a716-446655440000/filename.jpg",
    "filename": "filename.jpg",
    "size": 1024,
    "contentType": "image/jpeg"
  }
}

Get Media

GET /media/uploads/agents/{agentId}/{filename}
GET /media/generated/{agentId}/{filename}
GET /media/uploads/channels/{channelId}/{filename}

Memory Management

Get Agent Memories

GET /api/memory/agents/{agentId}/memories?table=messages&limit=50&offset=0

Response:

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "agentId": "550e8400-e29b-41d4-a716-446655440001",
        "entityId": "550e8400-e29b-41d4-a716-446655440002",
        "content": {
          "text": "Hello, how can you help me?",
          "source": "user_message"
        },
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

Search Memories

POST /api/memory/agents/{agentId}/search
Content-Type: application/json

{
  "query": "help with coding",
  "table": "messages",
  "limit": 10
}

Delete Memory

DELETE /api/memory/agents/{agentId}/memories/{memoryId}

Audio Processing

Transcribe Audio

POST /api/audio/transcribe
Content-Type: multipart/form-data

{
  "audio": <audio_file>,
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "success": true,
  "data": {
    "transcription": "Hello, this is a test transcription."
  }
}

Generate Speech

POST /api/audio/generate
Content-Type: application/json

{
  "text": "Hello, this is a test message.",
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

System Management

Health Check

GET /api/server/ping

Response:

{
  "success": true,
  "data": {
    "message": "Server is healthy",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Get System Status

GET /api/system/status

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 3600,
    "memory": {
      "used": 123456789,
      "total": 1073741824
    },
    "agents": {
      "active": 2,
      "total": 2
    }
  }
}

Environment Configuration

GET /api/system/environment
POST /api/system/environment

Error Handling

All API endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "message": "Agent not found",
    "code": "AGENT_NOT_FOUND",
    "details": {}
  }
}

Common Error Codes

  • 400 - Bad Request: Invalid request format or parameters
  • 401 - Unauthorized: Missing or invalid API key
  • 403 - Forbidden: Access denied
  • 404 - Not Found: Resource not found
  • 422 - Unprocessable Entity: Validation error
  • 500 - Internal Server Error: Server error

Rate Limiting

The API implements rate limiting to prevent abuse:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

Best Practices

Request Headers

Content-Type: application/json
X-API-KEY: your-secret-token
Accept: application/json

Error Handling

async function apiCall() {
  try {
    const response = await fetch("/api/agents", {
      headers: {
        "X-API-KEY": process.env.ELIZA_SERVER_AUTH_TOKEN,
      },
    });

    const data = await response.json();

    if (!data.success) {
      throw new Error(data.error.message);
    }

    return data.data;
  } catch (error) {
    console.error("API Error:", error);
    throw error;
  }
}

Pagination

// Handle paginated responses
async function getAllMessages(channelId, limit = 50) {
  const messages = [];
  let before = null;

  while (true) {
    const params = new URLSearchParams({
      limit: limit.toString(),
      ...(before && { before }),
    });

    const response = await fetch(`/api/messaging/central-channels/${channelId}/messages?${params}`);

    const data = await response.json();

    if (!data.success || !data.data.messages.length) {
      break;
    }

    messages.push(...data.data.messages);
    before = data.data.messages[data.data.messages.length - 1].createdAt;
  }

  return messages;
}

The elizaOS REST API provides a comprehensive interface for building applications that interact with agents and manage communication workflows.

Server Architecture

Complete guide to ElizaOS server architecture, AgentServer class, and lifecycle management

REST API Reference

Complete reference for ElizaOS REST API endpoints