# Live Shared Thread

Opens the real-time co-working **event stream** for the thread behind a share link, for a recipient who presents the link's slug. Once joined, the recipient receives the same live events as the thread owner — `message.created`, presence updates, run lifecycle events, and the assistant's streamed tokens — in real time.

Allowed **only** when the link's `access_level` is `live` (`403` otherwise); `view` and `fork` links cannot join live co-working. An unknown or unauthorized link returns `404`, and a revoked or expired one returns a validation error.

The response is an [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream (`Content-Type: text/event-stream`). Each event is delivered as an SSE `data:` frame carrying a JSON payload.

## Authentication

Requires **user** authentication. Authenticate with a Bearer token or `x-api-key` header — though share links resolve against a recipient user, so user auth is required in practice. Native `EventSource` clients that cannot set an `Authorization` header may pass the token via the `token` query param.

## Path Parameters

**`slug`** string required

The share-link slug, taken from the share URL.

## Query Parameters

**`token`** string optional

Access token for clients that cannot set an `Authorization` header (native `EventSource`). Ignored when a header credential is present.

## Returns

A `text/event-stream` response. The connection stays open and emits live co-working events as SSE frames. Event payloads include:

- **message.created** — a new message was added to the thread. Carries `message_id`, `role`, `created_by_user_id`, `sender_name` / `sender_avatar_url` (null for assistant and tool rows), and `created_at` (ISO-8601 UTC, the row's own timestamp). It carries **no message content**: bodies are authorization-filtered per reader on the way out, so they never ride a channel broadcast to every participant. Use `created_at` to tell whether you are behind, then fetch the gap with `GET /v1/shared-threads/{slug}/messages?after={last_rendered_message_id}&order=asc`. De-duplicate on `message_id` — a reconnect replays a bounded recent tail.
- **presence.*** — a participant joined, left, or changed activity (viewing / typing / prompting).
- **run.*** — assistant run lifecycle (started, progress, completed).
- assistant token deltas — the assistant's response streamed token-by-token.


## Code Examples

### cURL


```bash
curl -N "https://api.aitronos.com/v1/shared-threads/abc123slug/live" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Python SDK


```python
from aitronos import Aitronos

client = Aitronos(api_key="", token="YOUR_TOKEN")
with client.threads.shared.live(slug="abc123slug") as stream:
    for event in stream:
        print(event.type, event.data)
```

### Python (requests)


```python
import json
import requests

with requests.get(
    "https://api.aitronos.com/v1/shared-threads/abc123slug/live",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    stream=True,
) as response:
    for line in response.iter_lines():
        if line and line.startswith(b"data: "):
            event = json.loads(line[len(b"data: ") :])
            print(event)
```

### JavaScript


```javascript
// Native EventSource cannot set headers, so pass the token via the query param.
const source = new EventSource(
  "https://api.aitronos.com/v1/shared-threads/abc123slug/live?token=YOUR_TOKEN",
);

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  console.log(payload);
};

// Alternatively, use fetch with an Authorization: Bearer header and read the
// SSE stream from the response body (works where EventSource headers are unavailable).
const response = await fetch(
  "https://api.aitronos.com/v1/shared-threads/abc123slug/live",
  {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  },
);
const reader = response.body.getReader();
```

## Response Examples

### Success (200) — SSE stream


```text
data: {"type": "presence.updated", "thread_id": "thread_5f8c2a1b9d4e4c3f8a7b6c5d4e3f2a1b", "users": [{"user_id": "usr_…", "state": "viewing"}]}

data: {"event": "message.created", "thread_id": "thread_5f8c…", "message_id": "msg_…", "role": "user", "sender_name": "Andreas Lackner", "created_at": "2026-08-04T14:16:59.134789+00:00"}

data: {"type": "run.completed", "run_id": "run_…"}
```

### Error — Link does not grant live access (403)


```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This share link does not grant live co-working access",
    "system_message": "Insufficient permissions",
    "type": "authorization_error",
    "status": 403,
    "details": {
      "link_id": "slink_2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
      "access_level": "view"
    },
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

### Error — Link not found or not authorized (404)


```json
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "That share link could not be found.",
    "system_message": "Share link unresolved for user",
    "type": "client_error",
    "status": 404,
    "details": {},
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

## Related Resources

- [Get Shared Thread](/api-reference/shared-threads/get-shared-thread) — Open the share link
- [Get Shared Thread Messages](/api-reference/shared-threads/get-shared-thread-messages) — Read the shared thread's messages
- [Send to Shared Thread](/api-reference/shared-threads/send-shared-thread) — Post a message to the live-shared thread
- [Reconnect to Shared Thread Stream](/api-reference/shared-threads/reconnect-shared-thread-stream) — Resume an in-flight response
- [Cancel Shared Thread Response](/api-reference/shared-threads/cancel-shared-thread-response) — Cancel your in-flight response
- [Import Shared Thread](/api-reference/shared-threads/import-shared-thread) — Fork the shared thread into your own