Package Exports

@elizaos/api-client
@elizaos/api-client/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@elizaos/api-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@elizaos/api-client

Type-safe API client for ElizaOS server.

Installation

bun add @elizaos/api-client

Usage

import { ElizaClient } from '@elizaos/api-client';

// Create client instance
const client = ElizaClient.create({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key', // optional
});

// List all agents
const { agents } = await client.agents.listAgents();

// Create a new agent
const agent = await client.agents.createAgent({
  name: 'My Agent',
  description: 'A helpful assistant',
});

// Send a message
const message = await client.messaging.postMessage(channelId, 'Hello, world!');

// Create a session for user-agent conversation
const session = await client.sessions.createSession({
  agentId: agent.id,
  userId: 'user-123',
  metadata: { platform: 'web' },
});

// Send a message in the session
const sessionMessage = await client.sessions.sendMessage(session.sessionId, {
  content: 'Hello, agent!',
});

// Upload media
const upload = await client.media.uploadAgentMedia(agentId, {
  file: myFile,
  filename: 'image.png',
});

// Quick one-off message with automatic polling (Jobs API)
const response = await client.jobs.ask('user-123', 'What is Bitcoin?');
console.log('Agent response:', response);

API Domains

Agents

CRUD operations for agents
Agent lifecycle management (start/stop)
World management
Plugin panels and logs

Messaging

Message submission and management
Channel operations
Server management
Message search

Sessions

Create and manage user-agent conversation sessions
Send and retrieve messages within sessions
Session metadata and lifecycle management
Automatic cleanup of inactive sessions

Jobs

One-off messaging with automatic response handling
Simple request/response pattern for agent interactions
Automatic polling with customizable strategies
Job status tracking and health metrics

Example:

// Simple ask pattern - returns the response directly
const response = await client.jobs.ask('user-id', 'What is Bitcoin?');

// Create and poll manually for more control
const result = await client.jobs.createAndPoll({
  userId: 'user-id',
  content: 'Complex analysis query',
  agentId: 'specific-agent-id', // Optional
  timeoutMs: 60000, // Optional
});

if (result.success) {
  console.log('Response:', result.job.result?.message.content);
  console.log('Processing time:', result.job.result?.processingTimeMs, 'ms');
}

// Poll with exponential backoff for long-running queries
const backoffResult = await client.jobs.createAndPollWithBackoff({
  userId: 'user-id',
  content: 'Long running task',
}, {
  initialInterval: 500,
  maxInterval: 5000,
  multiplier: 1.5,
});

// Get job status manually
const job = await client.jobs.getJob('job-id');
console.log('Status:', job.status);

// List all jobs
const { jobs } = await client.jobs.list({ 
  status: JobStatus.COMPLETED,
  limit: 10 
});

// Check health metrics
const health = await client.jobs.health();
console.log('Success rate:', health.metrics.successRate);

Memory

Agent memory management
Room operations
World management

Audio

Speech processing
Text-to-speech
Audio transcription

Media

File uploads for agents and channels

Server

Health checks and status
Runtime debugging
Log management

System

Environment configuration

Error Handling

import { ApiError } from '@elizaos/api-client';

try {
  await client.agents.getAgent(agentId);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`Error ${error.code}: ${error.message}`);
    if (error.details) {
      console.error('Details:', error.details);
    }
  }
}

TypeScript Support

This package is written in TypeScript and provides full type definitions for all API endpoints, request parameters, and responses.