API Overview

agtOS exposes three protocol interfaces. Each serves a different use case — pick the one that fits your integration.

REST API

Port 4102 — 40+ endpointsHealth, chat, memory, scheduling, devices, configuration, and Prometheus metrics. Used by the CLI, dashboard, and external integrations.

WebSocket

Port 3000 — Real-time audioBidirectional PCM audio streaming with session management, transcripts, word timestamps, and TTS playback.

MCP Tools

Port 4100 — 10 built-in toolsVoice, system, memory, workflow, and scheduling tools via Streamable HTTP. Connect from Claude Desktop, Cursor, or any MCP client.

Authentication

All API endpoints support opt-in authentication via the AGTOS_API_KEY environment variable.

Enabled (production)
Disabled (development)

When AGTOS_API_KEY is set, all /api/* endpoints require a Bearer token:

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:4102/api/health

Health endpoints (/health, /metrics) remain open for monitoring.

When AGTOS_API_KEY is not set, all endpoints are open:

curl http://localhost:4102/api/health

This is the default for local development.

Rate limiting

All API endpoints use token bucket rate limiting per client IP:

Scope	Default	Environment Variable
General API (`/api/*`)	100 req/min	`API_RATE_LIMIT`
Chat, Tasks, Credentials	20 req/min	`CHAT_RATE_LIMIT`

Rate limit headers are included on every response:

X-RateLimit-Remaining: 98

Quick examples

curl http://localhost:4102/api/health

curl -X POST http://localhost:4102/api/chat \
  -H "Content-Type: application/json" \
  -d '{"text": "What time is it?"}'

curl "http://localhost:4102/api/memory/search?q=weather&limit=5"

# claude_desktop_config.json
{
  "mcpServers": {
    "agtos": { "url": "http://localhost:4100/mcp" }
  }
}

REST API

WebSocket

MCP Tools

​Authentication

​Rate limiting

​Quick examples

Authentication

Rate limiting

Quick examples