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

# Loom

> Threads, messages, runs, and traces. The HTTP surface of an embedded agent.

Loom is one conversation model with two ingress modes. The objects are the same.

```
Thread
  └── Message[]     the conversation
  └── Run[]         one turn each
        └── Trace   turns, tool calls, outcomes
```

| Object                              | Id   | Endpoints                                                |
| ----------------------------------- | ---- | -------------------------------------------------------- |
| [Thread](/api-reference/thread)     | UUID | `POST /v1/loom/threads`, `GET /v1/loom/threads`          |
| [Message](/api-reference/message)   | UUID | `POST …/messages`, `GET …/messages`                      |
| [Run](/api-reference/run)           | UUID | `GET /v1/loom/runs/:id`, `GET …/trace`, `POST …/outcome` |
| [Realtime](/api-reference/realtime) | —    | `GET /v1/loom/realtime/config`, `POST …/auth`            |

Agents are named by public id (`agent_…`). Connections are named by UUID (or, in relay, by name). Threads, runs, messages, and tool calls are UUIDs.

## Authentication

A JWT bearer is **direct** — subject from `sub`, optional connection from `conn`. Anything else is **relay** — workspace API key, subject from `Patchwork-Subject`, host from `Patchwork-Connection`.

See [Direct](/guides/loom-direct) and [Relay](/guides/loom-relay).

## Run lifecycle

```
POST …/messages  →  running
                 →  awaiting_input     POST the answer on the same thread
                 →  awaiting_outcome   POST …/outcome  { occurred | failed }
                 →  closed | failed
```

A `202` from send-message is the run, not the assistant's reply. Poll the run or subscribe to `private-thread-{id}`.