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

# Api reference

# API Reference

## Base URL

* Development: `http://localhost:4020`
* Production: Configurable via settings

## Authentication

### Token Generation

```http theme={null}
POST /api/auth/token
Content-Type: application/json

{
  "password": "optional-password"
}
```

**Response**

```json theme={null}
{
  "token": "jwt-token-string",
  "expiresIn": 86400
}
```

## Session Management

### Create Session

```http theme={null}
POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "command": "zsh",
  "args": [],
  "cwd": "/Users/username",
  "env": {},
  "name": "Session Name",
  "cols": 80,
  "rows": 24
}
```

**Response**

```json theme={null}
{
  "id": "session-uuid",
  "name": "Session Name",
  "created": "2024-01-01T00:00:00Z",
  "status": "running",
  "pid": 12345
}
```

### List Sessions

```http theme={null}
GET /api/sessions
Authorization: Bearer <token>
```

**Response**

```json theme={null}
[
  {
    "id": "session-uuid",
    "name": "Session 1",
    "created": "2024-01-01T00:00:00Z",
    "status": "running",
    "pid": 12345
  }
]
```

### Get Session Details

```http theme={null}
GET /api/sessions/:id
Authorization: Bearer <token>
```

### Delete Session

```http theme={null}
DELETE /api/sessions/:id
Authorization: Bearer <token>
```

### Resize Terminal

```http theme={null}
POST /api/sessions/:id/resize
Authorization: Bearer <token>
Content-Type: application/json

{
  "cols": 120,
  "rows": 40
}
```

## WebSocket Connection

### WebSocket v3 (`/ws`)

* Endpoint: `GET /ws` (WebSocket upgrade)
* Framing: binary v3 frames (`"VT"` magic, version `3`, type, sessionId, payload)
* Multiplexing: one socket carries multiple session subscriptions

Protocol details: `docs/websocket.md`.

```javascript theme={null}
const ws = new WebSocket('ws://localhost:4020/ws?token=JWT_TOKEN');
ws.binaryType = 'arraybuffer';
```

## Health Check

### Server Status

```http theme={null}
GET /api/health
```

**Response**

```json theme={null}
{
  "status": "healthy",
  "uptime": 3600,
  "version": "1.0.0",
  "sessions": 5
}
```

## Error Responses

| Status | Error        | Description            |
| ------ | ------------ | ---------------------- |
| 400    | Bad Request  | Invalid parameters     |
| 401    | Unauthorized | Missing/invalid token  |
| 404    | Not Found    | Session not found      |
| 409    | Conflict     | Session already exists |
| 500    | Server Error | Internal error         |

**Error Format**

```json theme={null}
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}
```

## Rate Limiting

* **Session Creation**: 10 per minute
* **API Calls**: 100 per minute
* **WebSocket Messages**: Unlimited

## Terminal Transport (WebSocket v3)

Terminal I/O uses a single `/ws` WebSocket with binary v3 framing and multiplexed sessions.

Details: `docs/websocket.md`.

## Session Recording

Sessions are recorded in asciinema v2 format:

```json theme={null}
{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1234567890,
  "env": {
    "SHELL": "/bin/zsh",
    "TERM": "xterm-256color"
  }
}
```

Event format:

```json theme={null}
[timestamp, "o", "output data"]
```

## See Also

* [WebSocket Protocol Details](protocols.md)
* [Authentication Guide](../features/authentication.md)
* [Server Implementation](../platform/web.md)