ContextQMD
Back to Eliza

elizaOS REST API Examples

packages/examples/rest-api/README.md

2.0.13.8 KB
Original Source

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

typescript
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

FrameworkLanguageDirectoryFull Runtime
ExpressTypeScriptexpress/Yes
HonoTypeScripthono/Yes
ElysiaTypeScriptelysia/Yes

Common API

All examples expose the same REST API:

GET /

Returns information about the agent.

bash
curl http://localhost:3000/

GET /health

Health check endpoint.

bash
curl http://localhost:3000/health

POST /chat

Send a message to the agent.

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

Response:

json
{
  "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.

bash
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)

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

Environment Variables

VariableDescriptionRequired
OPENAI_API_KEYOpenAI API keyYes
PORTServer port (default: 3000)No
CHARACTER_NAMEAgent nameNo
CHARACTER_BIOAgent bio/descriptionNo

Important: Never Call Plugins Directly

DO NOT do this:

typescript
// ❌ WRONG - Never call plugin functions directly
import { generateElizaResponse } from "@elizaos/plugin-eliza-classic";
const response = generateElizaResponse(message);

DO this instead:

typescript
// ✅ 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