REST API Reference

Overview

The ElizaOS REST API provides comprehensive endpoints for managing agents, messaging, memory, media, and system operations. All endpoints are prefixed with /api and return JSON responses.

Base Configuration

Base URL

http://localhost:3000/api

Authentication

If ELIZA_SERVER_AUTH_TOKEN is set, include the API key in headers:

X-API-KEY: your-api-key

Response Format

Success Response:

{
  "success": true,
  "data": {
    /* endpoint-specific data */
  }
}

Error Response:

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

Agent Management

List All Agents

GET /api/agents

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent-uuid",
        "name": "Agent Name",
        "characterName": "Character Name",
        "bio": "Agent biography",
        "status": "active" | "inactive"
      }
    ]
  }
}

Get Agent Details

GET /api/agents/:agentId

Response:

{
  "success": true,
  "data": {
    "id": "agent-uuid",
    "name": "Agent Name",
    "bio": ["Biography lines"],
    "lore": ["Lore entries"],
    "knowledge": ["Knowledge items"],
    "topics": ["conversation", "topics"],
    "status": "active" | "inactive"
  }
}

Create Agent

POST /api/agents

Request Body:

{
  "characterJson": {
    /* character configuration */
  },
  // OR
  "characterPath": "/path/to/character.json",
  // OR
  "agent": {
    /* agent configuration */
  }
}

Start Agent

POST /api/agents/:agentId/start

Response:

{
  "success": true,
  "data": {
    "id": "agent-uuid",
    "character": {
      /* character data */
    },
    "status": "active"
  }
}

Stop Agent

POST /api/agents/:agentId/stop

Messaging

Core Messaging

Submit Message

POST /api/messaging/submit

Request Body:

{
  "channel_id": "channel-uuid",
  "server_id": "server-uuid",
  "author_id": "author-uuid",
  "content": "Message content",
  "in_reply_to_message_id": "message-uuid",
  "source_type": "agent_response",
  "raw_message": {
    "thought": "Agent's internal thought",
    "actions": ["action1", "action2"]
  },
  "metadata": {
    "agentName": "Agent Name",
    "attachments": []
  }
}

Complete Message

POST /api/messaging/complete

Request Body:

{
  "channel_id": "channel-uuid",
  "server_id": "server-uuid"
}

Ingest External Message

POST /api/messaging/ingest-external

Request Body:

{
  "channel_id": "channel-uuid",
  "server_id": "server-uuid",
  "author_id": "author-uuid",
  "author_display_name": "User Name",
  "content": "Message content",
  "source_id": "platform-message-id",
  "source_type": "discord",
  "raw_message": {},
  "metadata": {}
}

Servers

List Servers

GET /api/messaging/servers

Response:

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "server-uuid",
        "name": "Server Name",
        "sourceType": "eliza_default",
        "metadata": {},
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Server Details

GET /api/messaging/servers/:serverId

Channels

List Channels for Server

GET /api/messaging/servers/:serverId/channels

Query Parameters:

participantId - Filter channels by participant

Response:

{
  "success": true,
  "data": {
    "channels": [
      {
        "id": "channel-uuid",
        "name": "Channel Name",
        "type": "dm" | "group",
        "participants": ["user-uuid-1", "user-uuid-2"],
        "lastMessageAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Create Channel

POST /api/messaging/servers/:serverId/channels

Request Body:

{
  "name": "Channel Name",
  "type": "dm" | "group",
  "participants": ["user-uuid-1", "user-uuid-2"],
  "metadata": {}
}

Send Message to Channel

POST /api/messaging/central-channels/:channelId/messages

Request Body:

{
  "author_id": "user-uuid",
  "content": "Message text",
  "in_reply_to_message_id": "message-uuid",
  "server_id": "server-uuid",
  "raw_message": {},
  "metadata": {
    "user_display_name": "User Name"
  },
  "source_type": "eliza_gui"
}

Get Channel Messages

GET /api/messaging/central-channels/:channelId/messages

Query Parameters:

limit - Number of messages (default: 50)
before - ISO timestamp for pagination

Response:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "message-uuid",
        "content": "Message content",
        "authorId": "author-uuid",
        "channelId": "channel-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "metadata": {}
      }
    ]
  }
}

Upload File to Channel

POST /api/messaging/central-channels/:channelId/upload

Request:

Content-Type: multipart/form-data
Field: file - Media file

Response:

{
  "success": true,
  "data": {
    "url": "/media/uploads/channels/{channelId}/filename.ext",
    "filename": "filename.ext"
  }
}

Delete Message

DELETE /api/messaging/messages/:messageId

Memory Management

Search Agent Memory

GET /api/memory/agents/:agentId/search

Query Parameters:

query - Search text (required)
limit - Result limit (default: 10)

Response:

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "memory-uuid",
        "content": {
          "text": "Memory content",
          "source": "conversation"
        },
        "similarity": 0.95,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Create Memory

POST /api/memory/agents/:agentId/memories

Request Body:

{
  "content": {
    "text": "Memory content",
    "type": "reflection" | "fact" | "dialogue"
  },
  "roomId": "optional-room-uuid"
}

Get Memories by Room

GET /api/memory/agents/:agentId/rooms/:roomId/memories

Query Parameters:

unique - Return only unique memories (default: true)

Remove Memory

DELETE /api/memory/agents/:agentId/memories/:memoryId

Remove All Memories

DELETE /api/memory/agents/:agentId/memories

Query Parameters:

confirm - Must be "true" to execute

Audio Processing

Transcribe Audio

POST /api/audio/transcribe

Request:

Content-Type: multipart/form-data
Field: audio - Audio file

Response:

{
  "success": true,
  "data": {
    "text": "Transcribed text",
    "service": "openai"
  }
}

Generate Speech

POST /api/audio/speech

Request Body:

{
  "text": "Text to convert to speech",
  "voice": "en-US-Neural2-A",
  "service": "google" | "openai" | "elevenlabs"
}

Response:

{
  "success": true,
  "data": {
    "audio": "base64-encoded-audio",
    "format": "mp3",
    "sampleRate": 24000
  }
}

Process Audio Conversation

POST /api/audio/agents/:agentId/conversation

Request:

Content-Type: multipart/form-data
Field: audio - Audio file
Field: roomId - Room UUID

Response:

{
  "success": true,
  "data": {
    "text": "User's transcribed speech",
    "response": "Agent's response",
    "audio": "base64-encoded-response-audio"
  }
}

Media Management

Upload Agent Media

POST /api/media/agents/:agentId/upload

Request:

Content-Type: multipart/form-data
Field: file - Media file

Response:

{
  "success": true,
  "data": {
    "url": "/media/uploads/agents/{agentId}/filename.ext",
    "filename": "filename.ext",
    "mimeType": "image/jpeg",
    "size": 12345
  }
}

Upload Channel Media

POST /api/media/channels/:channelId/upload

Generate Media

POST /api/media/agents/:agentId/generate

Request Body:

{
  "prompt": "Image generation prompt",
  "type": "image",
  "service": "openai"
}

Response:

{
  "success": true,
  "data": {
    "url": "/media/generated/{agentId}/generated-image.png",
    "metadata": {
      "prompt": "Original prompt",
      "model": "dall-e-3"
    }
  }
}

Server Management

Health Monitoring

Ping

GET /api/server/ping

Response:

{
  "pong": true,
  "timestamp": 1234567890
}

Hello World

GET /api/server/hello

Response:

{
  "message": "Hello World!"
}

System Status

GET /api/server/status

Response:

{
  "status": "ok",
  "agentCount": 3,
  "timestamp": "2024-01-01T00:00:00Z"
}

Health Check

GET /api/server/health

Response:

{
  "status": "OK",
  "version": "1.2.0",
  "timestamp": "2024-01-01T00:00:00Z",
  "dependencies": {
    "agents": "healthy"
  }
}

Server Stop

POST /api/server/stop

Response:

{
  "message": "Server stopping..."
}

Debugging

Debug Information

GET /api/server/debug

Response:

{
  "success": true,
  "data": {
    "environment": "development",
    "nodeVersion": "20.0.0",
    "elizaVersion": "1.2.0",
    "plugins": ["@elizaos/plugin-discord", "@elizaos/plugin-twitter"]
  }
}

Logging

Stream Logs

GET /api/server/logs

Query Parameters:

level - Log level filter (debug, info, warn, error)
agentId - Filter by specific agent
limit - Number of log entries (default: 100)

Response:

{
  "success": true,
  "data": {
    "logs": [
      {
        "level": "info",
        "timestamp": "2024-01-01T00:00:00Z",
        "message": "Log message",
        "agentId": "agent-uuid",
        "metadata": {}
      }
    ]
  }
}

System Configuration

Environment Management

Get Local Environment Variables

GET /api/system/env/local

Response:

{
  "success": true,
  "data": {
    "NODE_ENV": "development",
    "SERVER_URL": "http://localhost:3000",
    "ELIZA_SERVER_PORT": "3000"
  }
}

Update Local Environment Variables

POST /api/system/env/local

Request Body:

{
  "content": {
    "NODE_ENV": "production",
    "SERVER_URL": "https://example.com",
    "ELIZA_SERVER_PORT": "3000"
  }
}

Response:

{
  "success": true,
  "message": "Local env updated"
}

Version Management

Get Version Information

GET /api/system/version

Response:

{
  "version": "1.2.0",
  "source": "server",
  "timestamp": "2024-01-01T00:00:00Z",
  "environment": "development",
  "uptime": 3600
}

TEE Operations

Generate Remote Attestation

POST /api/tee/attestation

Request Body:

{
  "reportData": "custom-report-data"
}

Response:

{
  "success": true,
  "data": {
    "attestation": "base64-encoded-attestation",
    "signature": "attestation-signature"
  }
}

Derive Key

POST /api/tee/derive-key

Request Body:

{
  "path": "/path/to/derive",
  "data": "input-data"
}

Error Codes

Common error codes returned by the API:

Code	Description
`INVALID_ID`	Invalid UUID format
`NOT_FOUND`	Resource not found
`INVALID_REQUEST`	Invalid request parameters
`DB_ERROR`	Database operation failed
`AUTH_REQUIRED`	Authentication required
`FORBIDDEN`	Insufficient permissions
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server error

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Default: 100 requests per minute per IP
File uploads: 10 requests per minute per IP
Can be configured via environment variables

CORS Configuration

CORS is enabled with the following defaults:

Origin: Configured via CORS_ORIGIN env var or *
Credentials: Enabled
Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Headers: Content-Type, Authorization, X-API-KEY

File Size Limits

JSON payloads: 100KB (configurable via EXPRESS_MAX_PAYLOAD)
File uploads: 10MB per file
Audio files: 25MB
Generated content: Limited by disk space

Best Practices

Always handle errors - Check for error responses
Use proper content types - Set Content-Type headers
Validate UUIDs - Ensure valid UUID format
Implement retries - Add exponential backoff
Cache responses - Use appropriate cache headers
Monitor rate limits - Track X-RateLimit headers
Secure file uploads - Validate file types and sizes

REST API Reference

On this page