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

# API Reference

> WebSocket RPC protocol reference for ArgentOS gateway — connection, authentication, and all available methods.

## Overview

The ArgentOS gateway exposes a WebSocket-based RPC interface on port 18789 (configurable). All dashboard interactions, CLI commands, and external integrations communicate through this protocol.

The protocol uses JSON-RPC style messages: each request has a `method` and `params`, each response returns a `result` or `error`.

## Connection

### WebSocket URL

<CodeGroup>
  ```text Local theme={null}
  ws://localhost:18789
  ```

  ```text Remote theme={null}
  wss://your-domain.com:18789
  ```
</CodeGroup>

### Authentication

After connecting, the client must authenticate with a challenge-response:

<Steps>
  <Step title="Server sends challenge">
    Server sends `connect.challenge` event with a nonce
  </Step>

  <Step title="Client responds">
    Client responds with the gateway token (from `~/.argentos/argent.json` or `ARGENT_GATEWAY_TOKEN`)
  </Step>

  <Step title="Server validates">
    Server validates and grants access
  </Step>
</Steps>

<Info>
  The gateway token is auto-generated on first run. It can be found in `argent.json` under `gateway.token` or retrieved via `argent gateway status`.
</Info>

### Client Registration

On successful auth, the client registers with:

```json theme={null}
{
  "method": "connect",
  "params": {
    "clientName": "dashboard",
    "clientDisplayName": "ArgentOS Dashboard",
    "mode": "operator"
  }
}
```

Client modes:

* `operator` -- Full access (dashboard, CLI)
* `node` -- Limited access (compute nodes)
* `device` -- Device access (paired devices)

## Request Format

```json theme={null}
{
  "id": "req-1",
  "method": "method.name",
  "params": { }
}
```

## Response Format

<CodeGroup>
  ```json Success theme={null}
  {
    "id": "req-1",
    "result": { }
  }
  ```

  ```json Error theme={null}
  {
    "id": "req-1",
    "error": {
      "code": -32600,
      "message": "Invalid request",
      "data": { }
    }
  }
  ```
</CodeGroup>

## Server-Sent Events

The gateway pushes events to connected clients:

| Event                     | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `connect.challenge`       | Authentication challenge                                |
| `agent`                   | Agent streaming output (tokens, tool calls, completion) |
| `chat`                    | Chat message updates                                    |
| `presence`                | Agent presence changes                                  |
| `tick`                    | Periodic tick (dashboard heartbeat)                     |
| `talk.mode`               | Voice mode changes                                      |
| `health`                  | Health status updates                                   |
| `heartbeat`               | Heartbeat cycle results                                 |
| `cron`                    | Cron job events                                         |
| `shutdown`                | Gateway shutting down                                   |
| `exec.approval.requested` | Command approval needed                                 |
| `exec.approval.resolved`  | Command approval resolved                               |
| `terminal`                | Terminal output                                         |
| `node.pair.requested`     | Node pairing request                                    |
| `device.pair.requested`   | Device pairing request                                  |

## Chat Methods

### chat.send

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

```json theme={null}
{
  "method": "chat.send",
  "params": {
    "message": "What tasks are pending?",
    "sessionKey": "main",
    "model": "anthropic/claude-sonnet-4-20250514",
    "thinking": "medium",
    "images": []
  }
}
```

Response streams via `agent` events with token deltas.

### chat.history

Retrieve chat history for a session.

```json theme={null}
{
  "method": "chat.history",
  "params": {
    "sessionKey": "main",
    "limit": 50
  }
}
```

### chat.abort

Stop a running agent turn.

```json theme={null}
{
  "method": "chat.abort",
  "params": {
    "sessionKey": "main"
  }
}
```

## Agent Methods

### agent

Send a command to the agent (general purpose).

```json theme={null}
{
  "method": "agent",
  "params": {
    "message": "Run the daily report",
    "sessionKey": "main"
  }
}
```

### agent.wait

Wait for a running agent turn to complete.

```json theme={null}
{
  "method": "agent.wait",
  "params": {
    "sessionKey": "main",
    "timeoutMs": 30000
  }
}
```

### agent.identity.get

Get the agent's identity information.

```json theme={null}
{
  "method": "agent.identity.get",
  "params": {}
}
```

## Configuration Methods

### config.get

Get the current configuration.

```json theme={null}
{
  "method": "config.get",
  "params": {}
}
```

### config.set

Set a configuration value.

```json theme={null}
{
  "method": "config.set",
  "params": {
    "path": "agents.defaults.thinkingDefault",
    "value": "medium"
  }
}
```

### config.patch

Apply multiple configuration changes atomically.

```json theme={null}
{
  "method": "config.patch",
  "params": {
    "patches": [
      { "path": "agents.defaults.heartbeat.every", "value": "45m" },
      { "path": "agents.defaults.contemplation.enabled", "value": true }
    ]
  }
}
```

### config.schema

Get the full configuration schema.

```json theme={null}
{
  "method": "config.schema",
  "params": {}
}
```

## Session Methods

### sessions.list

List all agent sessions.

```json theme={null}
{
  "method": "sessions.list",
  "params": {}
}
```

### sessions.preview

Preview a session's content.

```json theme={null}
{
  "method": "sessions.preview",
  "params": {
    "sessionKey": "main"
  }
}
```

### sessions.reset

Reset a session (clear history).

```json theme={null}
{
  "method": "sessions.reset",
  "params": {
    "sessionKey": "main"
  }
}
```

### sessions.compact

Compact a session (summarize and truncate old messages).

```json theme={null}
{
  "method": "sessions.compact",
  "params": {
    "sessionKey": "main"
  }
}
```

## Cron Methods

### cron.list

List all cron jobs.

```json theme={null}
{
  "method": "cron.list",
  "params": {
    "includeDisabled": false
  }
}
```

### cron.add

Create a new cron job.

```json theme={null}
{
  "method": "cron.add",
  "params": {
    "name": "Morning Briefing",
    "schedule": { "kind": "at", "at": "06:00" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "Generate the daily briefing"
    }
  }
}
```

### cron.update

Update an existing cron job.

```json theme={null}
{
  "method": "cron.update",
  "params": {
    "id": "job-uuid",
    "enabled": false
  }
}
```

### cron.run

Force-run a cron job.

```json theme={null}
{
  "method": "cron.run",
  "params": {
    "id": "job-uuid",
    "mode": "force"
  }
}
```

### cron.remove

Delete a cron job.

```json theme={null}
{
  "method": "cron.remove",
  "params": {
    "id": "job-uuid"
  }
}
```

## Model Methods

### models.list

List available models and providers.

```json theme={null}
{
  "method": "models.list",
  "params": {}
}
```

Returns provider registry entries with model capabilities, pricing, and availability status.

## Knowledge Methods

### knowledge.search

Search the knowledge library.

```json theme={null}
{
  "method": "knowledge.search",
  "params": {
    "query": "deployment procedures",
    "collection": "corporate",
    "limit": 10
  }
}
```

### knowledge.ingest

Ingest a document into the knowledge library.

```json theme={null}
{
  "method": "knowledge.ingest",
  "params": {
    "collection": "corporate",
    "filename": "handbook.pdf",
    "content": "base64-encoded-content"
  }
}
```

### knowledge.library.list

List documents in the knowledge library.

```json theme={null}
{
  "method": "knowledge.library.list",
  "params": {
    "collection": "corporate"
  }
}
```

### knowledge.collections.list

List all knowledge collections.

```json theme={null}
{
  "method": "knowledge.collections.list",
  "params": {}
}
```

## Execution Worker Methods

### execution.worker.status

Get execution worker status and metrics.

```json theme={null}
{
  "method": "execution.worker.status",
  "params": {}
}
```

### execution.worker.runNow

Trigger an immediate execution worker cycle.

```json theme={null}
{
  "method": "execution.worker.runNow",
  "params": {}
}
```

### execution.worker.pause / resume

Pause or resume the execution worker.

```json theme={null}
{
  "method": "execution.worker.pause",
  "params": {}
}
```

## Channel Methods

### channels.status

Get status of all configured channels.

```json theme={null}
{
  "method": "channels.status",
  "params": {}
}
```

### send

Send an outbound message through a channel.

```json theme={null}
{
  "method": "send",
  "params": {
    "channel": "telegram",
    "action": "send",
    "to": "user:123456",
    "message": "Hello from ArgentOS"
  }
}
```

## Health & Status Methods

### health

Get gateway health status.

```json theme={null}
{
  "method": "health",
  "params": {}
}
```

### status

Get comprehensive system status.

```json theme={null}
{
  "method": "status",
  "params": {}
}
```

### system-presence

Get current agent presence state.

```json theme={null}
{
  "method": "system-presence",
  "params": {}
}
```

## TTS Methods

### tts.status

Get TTS provider status.

```json theme={null}
{
  "method": "tts.status",
  "params": {}
}
```

### tts.convert

Convert text to speech.

```json theme={null}
{
  "method": "tts.convert",
  "params": {
    "text": "Hello, this is a test.",
    "voice": "Jessica"
  }
}
```

## Agents Methods

### agents.list

List all configured agents.

```json theme={null}
{
  "method": "agents.list",
  "params": {}
}
```

### agents.files.list / get / set

Manage agent alignment documents.

```json theme={null}
{
  "method": "agents.files.get",
  "params": {
    "agentId": "main",
    "filename": "SOUL.md"
  }
}
```

## Error Codes

| Code     | Name              | Description                      |
| -------- | ----------------- | -------------------------------- |
| `-32600` | Invalid Request   | Malformed request                |
| `-32601` | Method Not Found  | Unknown method name              |
| `-32602` | Invalid Params    | Parameter validation failed      |
| `-32603` | Internal Error    | Server-side error                |
| `-32000` | Agent Busy        | Agent is already processing      |
| `-32001` | Session Not Found | Requested session does not exist |
| `-32002` | Auth Failed       | Authentication failure           |

## Scopes

Methods are grouped into access scopes:

| Scope                | Description           | Example Methods               |
| -------------------- | --------------------- | ----------------------------- |
| `operator.read`      | Read-only access      | health, status, models.list   |
| `operator.write`     | Read-write access     | config.set, cron.add, send    |
| `operator.admin`     | Administrative access | exec.approvals.set            |
| `operator.approvals` | Approval flow         | exec.approval.request/resolve |
| `operator.pairing`   | Device pairing        | node.pair.*, device.pair.*    |

## Key Files

| File                                 | Description                       |
| ------------------------------------ | --------------------------------- |
| `src/gateway/server-methods.ts`      | Method handler registration       |
| `src/gateway/server-methods-list.ts` | Method and event catalog          |
| `src/gateway/server-methods/`        | Individual method handler modules |
| `src/gateway/protocol/`              | Protocol schemas and validation   |
| `src/gateway/server.impl.ts`         | WebSocket server implementation   |