REST API

Complete reference for all Saiki REST API endpoints. All endpoints are prefixed with /api/.

Base URL

http://localhost:3001/api

Message Endpoints

Send Message (Synchronous)

Send a message to the agent and receive the complete response.

POST /api/message-sync

Request Body

Field	Type	Required	Description
`message`	string	✅	The message to send to the agent
`imageData`	object	❌	Optional image data for multimodal input
`imageData.base64`	string	❌	Base64 encoded image string
`imageData.mimeType`	string	❌	Image MIME type (e.g., "image/png")

Example Request

curl -X POST http://localhost:3001/api/message-sync \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What files are in the current directory?",
    "imageData": {
      "base64": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      "mimeType": "image/png"
    }
  }'

Example Response

{
  "success": true,
  "response": "I can see several files in the current directory:\n\n1. package.json - Node.js project configuration\n2. README.md - Project documentation\n3. src/ - Source code directory\n4. docs/ - Documentation files\n\nWould you like me to examine any specific file in more detail?",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Status Codes

Code	Description
`200`	Success - Message processed
`400`	Bad Request - Invalid message format
`429`	Rate Limit - Too many requests
`500`	Server Error - Processing failed

Send Message (Asynchronous)

Send a message to the agent asynchronously. Use WebSocket to receive the response.

POST /api/message

Request Body

Field	Type	Required	Description
`message`	string	✅	The message to send to the agent

Example Request

curl -X POST http://localhost:3001/api/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Analyze the project structure"}'

Example Response

{
  "status": "processing",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

WebSocket Required

The actual response will be sent via WebSocket events. See WebSocket API for details.

Reset Conversation

Clear the agent's conversation history for a fresh start.

POST /api/reset

Request Body

No request body required (can be empty or {}).

Example Request

curl -X POST http://localhost:3001/api/reset \
  -H "Content-Type: application/json"

Example Response

{
  "status": "reset initiated",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

MCP Server Management

List MCP Servers

Get all connected and attempted MCP servers with their status.

GET /api/mcp/servers

Example Request

curl http://localhost:3001/api/mcp/servers

Example Response

{
  "servers": [
    {
      "id": "filesystem",
      "name": "filesystem",
      "status": "connected",
      "type": "stdio",
      "description": "File system operations"
    },
    {
      "id": "puppeteer",
      "name": "puppeteer",
      "status": "error",
      "type": "stdio",
      "error": "Failed to start server process"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Server Status Values

Status	Description
`connected`	Server is running and connected
`connecting`	Server is starting up
`error`	Server failed to start or crashed
`disconnected`	Server was disconnected

Connect New MCP Server

Dynamically connect a new MCP server to the agent at runtime.

POST /api/connect-server

Request Body

Field	Type	Required	Description
`name`	string	✅	Unique name for the server
`config`	object	✅	Server configuration
`config.type`	string	✅	Server type (usually "stdio")
`config.command`	string	✅	Command to start the server
`config.args`	array	❌	Command arguments
`config.env`	object	❌	Environment variables

Example Request

curl -X POST http://localhost:3001/api/connect-server \
  -H "Content-Type: application/json" \
  -d '{
    "name": "database",
    "config": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@truffle-ai/database-server"],
      "env": {
        "DB_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }'

Example Response

{
  "status": "connected",
  "name": "database",
  "server": {
    "id": "database",
    "name": "database",
    "status": "connected",
    "type": "stdio"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Tool Management

List Server Tools

Get all tools available from a specific MCP server.

GET /api/mcp/servers/{serverId}/tools

Path Parameters

Parameter	Type	Required	Description
`serverId`	string	✅	The ID/name of the MCP server

Example Request

curl http://localhost:3001/api/mcp/servers/filesystem/tools

Example Response

{
  "tools": [
    {
      "id": "readFile",
      "name": "readFile",
      "description": "Read the contents of a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file to read"
          }
        },
        "required": ["path"]
      }
    },
    {
      "id": "writeFile",
      "name": "writeFile",
      "description": "Write content to a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file to write"
          },
          "content": {
            "type": "string",
            "description": "Content to write to the file"
          }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Execute Tool

Directly execute a specific tool on a connected MCP server.

POST /api/mcp/servers/{serverId}/tools/{toolName}/execute

Path Parameters

Parameter	Type	Required	Description
`serverId`	string	✅	The ID/name of the MCP server
`toolName`	string	✅	The name of the tool to execute

Request Body

The request body should match the tool's inputSchema. See the tool list endpoint for schema details.

Example Request

curl -X POST http://localhost:3001/api/mcp/servers/filesystem/tools/readFile/execute \
  -H "Content-Type: application/json" \
  -d '{"path": "./README.md"}'

Example Response

{
  "success": true,
  "data": {
    "content": "# My Project\n\nThis is a sample README file...",
    "encoding": "utf-8",
    "size": 1234
  },
  "execution": {
    "toolName": "readFile",
    "serverId": "filesystem",
    "duration": 45
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Configuration

Export Configuration

Get the current agent configuration in YAML format. Sensitive information is omitted.

GET /api/config.yaml

Example Request

curl http://localhost:3001/api/config.yaml

Example Response

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "."

llm:
  provider: openai
  model: gpt-4.1-mini
  apiKey: "***REDACTED***"
  systemPrompt: |
    You are Saiki, a helpful AI assistant with access to tools.
    Use these tools when appropriate to answer user queries.

version: "0.2.5"

Health Check

API Health

Check if the Saiki API is running and healthy.

GET /api/health

Example Request

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

Example Response

{
  "status": "healthy",
  "version": "0.2.5",
  "uptime": 3600,
  "agent": {
    "status": "ready",
    "connectedServers": 2
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Responses

All endpoints return errors in a consistent format:

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {
      "field": "Additional error context",
      "suggestion": "How to fix this error"
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common Error Codes

Code	Status	Description
`INVALID_REQUEST`	400	Request format is invalid
`MISSING_FIELD`	400	Required field is missing
`UNAUTHORIZED`	401	Authentication required
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`SERVER_NOT_FOUND`	404	MCP server not found
`TOOL_NOT_FOUND`	404	Tool not found on server
`TOOL_EXECUTION_FAILED`	500	Tool execution failed
`AGENT_ERROR`	500	Agent processing error
`INTERNAL_ERROR`	500	Unexpected server error

Example Error Responses

Missing Required Field

{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "Missing required field: message",
    "details": {
      "field": "message",
      "suggestion": "Include a 'message' field in your request body"
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Tool Execution Failed

{
  "success": false,
  "error": {
    "code": "TOOL_EXECUTION_FAILED",
    "message": "Failed to execute tool: readFile",
    "details": {
      "toolName": "readFile",
      "serverId": "filesystem",
      "reason": "File not found: ./nonexistent.txt"
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Rate Limiting

API responses include rate limiting headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
Content-Type: application/json

See Authentication for detailed rate limiting information.

Next Steps

Need real-time updates? Check out WebSocket API
Want code examples? Browse SDKs & Examples
Having issues? See Error Handling

Base URL​

Message Endpoints​

Send Message (Synchronous)​

Request Body​

Example Request​

Example Response​

Status Codes​

Send Message (Asynchronous)​

Request Body​

Example Request​

Example Response​

Reset Conversation​

Request Body​

Example Request​

Example Response​

MCP Server Management​

List MCP Servers​

Example Request​

Example Response​

Server Status Values​

Connect New MCP Server​

Request Body​

Example Request​

Example Response​

Tool Management​

List Server Tools​

Path Parameters​

Example Request​

Example Response​

Execute Tool​

Path Parameters​

Request Body​

Example Request​

Example Response​

Configuration​

Export Configuration​

Example Request​

Example Response​

Health Check​

API Health​

Example Request​

Example Response​

Error Responses​

Error Response Format​

Common Error Codes​

Example Error Responses​

Missing Required Field​

Tool Execution Failed​

Rate Limiting​

Next Steps​

Base URL

Message Endpoints

Send Message (Synchronous)

Request Body

Example Request

Example Response

Status Codes

Send Message (Asynchronous)

Request Body

Example Request

Example Response

Reset Conversation

Request Body

Example Request

Example Response

MCP Server Management

List MCP Servers

Example Request

Example Response

Server Status Values

Connect New MCP Server

Request Body

Example Request

Example Response

Tool Management

List Server Tools

Path Parameters

Example Request

Example Response

Execute Tool

Path Parameters

Request Body

Example Request

Example Response

Configuration

Export Configuration

Example Request

Example Response

Health Check

API Health

Example Request

Example Response

Error Responses

Error Response Format

Common Error Codes

Example Error Responses

Missing Required Field

Tool Execution Failed

Rate Limiting

Next Steps