> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Three protocol interfaces for interacting with agtOS

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

<CardGroup cols={3}>
  <Card title="REST API" icon="server" href="/api-reference/http-endpoints">
    **Port 4102** — 40+ endpoints

    Health, chat, memory, scheduling, devices, configuration, and Prometheus metrics. Used by the CLI, dashboard, and external integrations.
  </Card>

  <Card title="WebSocket" icon="wave-sine" href="/api-reference/websocket">
    **Port 3000** — Real-time audio

    Bidirectional PCM audio streaming with session management, transcripts, word timestamps, and TTS playback.
  </Card>

  <Card title="MCP Tools" icon="wrench" href="/api-reference/mcp-tools">
    **Port 4100** — 10 built-in tools

    Voice, system, memory, workflow, and scheduling tools via Streamable HTTP. Connect from Claude Desktop, Cursor, or any MCP client.
  </Card>
</CardGroup>

## Authentication

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

<Tabs>
  <Tab title="Enabled (production)">
    When `AGTOS_API_KEY` is set, all `/api/*` endpoints require a Bearer token:

    ```bash theme={null}
    curl -H "Authorization: Bearer your-api-key" \
      http://localhost:4102/api/health
    ```

    Health endpoints (`/health`, `/metrics`) remain open for monitoring.
  </Tab>

  <Tab title="Disabled (development)">
    When `AGTOS_API_KEY` is not set, all endpoints are open:

    ```bash theme={null}
    curl http://localhost:4102/api/health
    ```

    This is the default for local development.
  </Tab>
</Tabs>

## 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

<CodeGroup>
  ```bash Health check theme={null}
  curl http://localhost:4102/api/health
  ```

  ```bash Send a chat message theme={null}
  curl -X POST http://localhost:4102/api/chat \
    -H "Content-Type: application/json" \
    -d '{"text": "What time is it?"}'
  ```

  ```bash Search memory theme={null}
  curl "http://localhost:4102/api/memory/search?q=weather&limit=5"
  ```

  ```bash Connect MCP (Claude Desktop) theme={null}
  # claude_desktop_config.json
  {
    "mcpServers": {
      "agtos": { "url": "http://localhost:4100/mcp" }
    }
  }
  ```
</CodeGroup>