---
title: "Open a WebSocket connection"
method: GET
path: "/v1/ws"
tags: ["WebSocket"]
---

# Open a WebSocket connection

`GET /v1/ws`

## Request

- Base URL: `https://anjal.app`
- URL: `https://anjal.app/v1/ws`
- Auth: API key in header `X-API-Key`

Upgrade this GET to a WebSocket. After the handshake, the server
sends a `connected` frame and the client sends a `subscribe`
frame to start receiving events.

This protocol is wire-compatible with agentmail.to's WebSocket
API — `workspace_ids` also accepts `pod_ids` as an alias.

### Client → server frames

```json
{ "type": "subscribe",
  "event_types": ["message.received", "message.sent"],
  "inbox_ids":    ["..."],
  "workspace_ids": ["..."] }
```

### Server → client frames

```json
{ "type": "connected", "inboxId": "...", "email": "..." }
{ "type": "subscribed", "event_types": [...], "inbox_ids": [...], "workspace_ids": [...] }
{ "type": "event",
  "event_type": "message.received",
  "event_id":   "evt_...",
  "message":    { "inbox_id": "...", "thread_id": "...", "from": "...", "to": ["..."], "subject": "...", "plain_body": "...", "html_body": "...", "timestamp": "..." },
  "thread":     { "thread_id": "...", "subject": "..." } }
{ "type": "ping" }
{ "type": "error", "message": "..." }
```

Use `?api_key=<key>` as a query parameter when your client
(e.g. browser `new WebSocket`) can't set the `X-API-Key`
header.

## Other responses

- `101`: Switching protocols
- `401`: Missing or invalid API key

---

[API](https://skmtc.dev/anjal/apis/anjal-api.md) · [All operations](https://skmtc.dev/anjal/apis/anjal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/anjal/apis/anjal-api/revisions/a4044778e294?raw)