elizaos--eliza/packages/examples/rest-api

elizaOS REST API Examples

This directory contains REST API examples for elizaOS using TypeScript web frameworks.

All examples use the canonical elizaOS implementation pattern:

runtime.messageService.handleMessage(runtime, messageMemory, callback)

The Canonical Pattern

Every example follows the same core pattern:

1. Create an AgentRuntime with plugins (sql, openai, etc.)
2. Initialize the runtime with await runtime.initialize()
3. Ensure connection for the user session
4. Create a message memory with the user's message
5. Call messageService.handleMessage() to process the message

TypeScript Example

import {
  AgentRuntime,
  ChannelType,
  createCharacter,
  createMessageMemory,
  stringToUuid,
} from "@elizaos/core";
import { openaiPlugin } from "@elizaos/plugin-openai";
import sqlPlugin from "@elizaos/plugin-sql";

// Create runtime
const runtime = new AgentRuntime({
  character: createCharacter({ name: "Eliza", bio: "A helpful AI assistant." }),
  plugins: [sqlPlugin, openaiPlugin],
});

await runtime.initialize();

// Handle a message
const messageMemory = createMessageMemory({
  id: uuidv4(),
  entityId: userId,
  roomId: stringToUuid("room"),
  content: { text: "Hello!", source: "api", channelType: ChannelType.API },
});

await runtime.messageService?.handleMessage(runtime, messageMemory, async (content) => {
  console.log("Response:", content.text);
  return [];
});

Available Examples

Framework	Language	Directory	Full Runtime
Express	TypeScript	express/	Yes
Hono	TypeScript	hono/	Yes
Elysia	TypeScript	elysia/	Yes

Common API

All examples expose the same REST API:

GET /

Returns information about the agent.

curl http://localhost:3000/

GET /health

Health check endpoint.

curl http://localhost:3000/health

POST /chat

Send a message to the agent.

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, how are you?"}'

Response:

{
  "response": "Hello! I'm doing well. How can I help you today?",
  "character": "Eliza",
  "userId": "generated-uuid"
}

POST /chat/stream (TypeScript only)

Send a message and receive a streaming response via Server-Sent Events.

curl -X POST http://localhost:3000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me a story"}'

Quick Start

TypeScript (Express, Hono, Elysia)

cd express  # or hono, elysia
bun install
OPENAI_API_KEY=your-key bun run start

Environment Variables

Variable	Description	Required
OPENAI_API_KEY	OpenAI API key	One provider key
OPENROUTER_API_KEY	OpenRouter API key	One provider key
ANTHROPIC_API_KEY	Anthropic API key	One provider key
ELIZA_API_KEY	Eliza Cloud API key	One provider key
PORT	Server port (default: 3000)	No
CHARACTER_NAME	Agent name	No
CHARACTER_BIO	Agent bio/description	No

Provider priority is OPENAI_API_KEY -> OPENROUTER_API_KEY -> ANTHROPIC_API_KEY -> ELIZA_API_KEY. If none is set, the server refuses to start.

Important: Never Call Plugins Directly

DO NOT do this:

// ❌ WRONG - Never call plugin functions directly
const response = await providerClient.chat.completions.create({
  messages: [{ role: "user", content: message }],
});

DO this instead:

// ✅ CORRECT - Always use the runtime's message service
await runtime.messageService?.handleMessage(runtime, messageMemory, callback);

The message service:

• Manages conversation context and memory
• Runs the shouldRespond classifier to decide whether to reply
• Invokes providers to gather context
• Executes actions based on the conversation
• Handles all model calls through the plugin system