Skip to main content

API Reference

Welcome to the Saiki API documentation! This comprehensive guide covers everything you need to integrate Saiki agents into your applications.

Overview​

Saiki provides both REST API and WebSocket API interfaces when running in web mode (saiki --mode web). These APIs allow you to:

  • Send messages to AI agents
  • Manage conversation state
  • Connect and manage MCP servers dynamically
  • Execute tools directly
  • Stream real-time responses
  • Monitor agent activity

Quick Start​

1. Start Saiki in Web Mode​

saiki --mode web
# or
npm start -- --mode web

2. Make Your First API Call​

curl -X POST http://localhost:3001/api/message-sync \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you help me with?"}'

3. Connect via WebSocket​

const ws = new WebSocket('ws://localhost:3001/');
ws.send(JSON.stringify({
  type: "message",
  content: "Hello from WebSocket!"
}));

API Sections​

Authentication​

Learn about API authentication, rate limiting, and security considerations.

REST API​

Complete reference for all HTTP endpoints:

  • Message endpoints
  • Server management
  • Tool execution
  • Configuration

WebSocket API​

Real-time communication with Saiki agents:

  • Connection setup
  • Message types
  • Event streaming
  • Error handling

SDKs & Examples​

Code examples and SDKs for popular languages:

  • JavaScript/TypeScript
  • Python
  • cURL examples
  • Integration patterns

Error Handling​

Understanding and handling API errors:

  • Error codes
  • Error responses
  • Retry strategies
  • Debugging tips

Key Features​

🔄 Real-time Streaming​

Get immediate responses as your agent thinks and processes:

// WebSocket streaming
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.event === 'chunk') {
    console.log('Agent thinking:', data.data.content);
  }
};

🛠️ Dynamic Tool Management​

Connect new tools to your agent at runtime:

// Add a new MCP server
await fetch('/api/connect-server', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'database',
    config: {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@truffle-ai/database-server']
    }
  })
});

🎯 Direct Tool Execution​

Execute specific tools without going through the agent:

// Execute a tool directly
const result = await fetch('/api/mcp/servers/filesystem/tools/readFile/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ path: './README.md' })
});

🖼️ Multimodal Support​

Send text and images to your agent:

// Send image with message
await fetch('/api/message-sync', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: "What's in this image?",
    imageData: {
      base64: "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      mimeType: "image/png"
    }
  })
});

Base URL​

By default, Saiki runs on:

  • Development: http://localhost:3001
  • Production: Your deployed URL

All API endpoints are prefixed with /api/ for REST calls.

Response Format​

All API responses follow this structure:

Success Response​

{
  "success": true,
  "data": { /* response data */ },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Response​

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: message",
    "details": { /* additional error context */ }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Rate Limits​

Current rate limits (subject to change):

  • REST API: 100 requests per minute per IP
  • WebSocket: 50 messages per minute per connection
  • File uploads: 10MB maximum size

Status & Health​

Check if your Saiki instance is running:

curl http://localhost:3001/api/health

Getting Help​

Next Steps​

  1. New to APIs? Start with Authentication to understand the basics
  2. Building a web app? Check out REST API endpoints
  3. Need real-time updates? Explore WebSocket API
  4. Want examples? Browse SDKs & Examples

Ready to build something amazing? Let's dive in! 🚀