> ## 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.

# The Thread object

> One conversation. Belongs to a subject. Holds messages and runs.

A thread is created against a published agent, then you post messages to it. Direct tokens only see their own threads. Relay without a subject sees the workspace.

Created:

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent": { "name": "Amber" },
  "subject_ref": "user_42"
}
```

Listed (summary):

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Send 50 USDC to Jane",
  "subject_ref": "user_42",
  "agent": { "name": "Amber" },
  "message_count": 4,
  "last_message": {
    "role": "assistant",
    "content": "I need Jane's account number.",
    "created_at": "2026-08-16T12:00:00Z"
  },
  "pending_elicitation": null,
  "pending_action": null,
  "created_at": "2026-08-16T11:58:00Z",
  "updated_at": "2026-08-16T12:00:00Z"
}
```

The first user message becomes the title (truncated). List is capped at 30, newest first.

## Attributes

<ResponseField name="id" type="uuid" required>
  Unique identifier for the thread.
</ResponseField>

<ResponseField name="title" type="string">
  Conversation title. Defaults to `"New conversation"` until the first message.
</ResponseField>

<ResponseField name="subject_ref" type="string">
  Acting user. From the token `sub` (direct) or `Patchwork-Subject` / `subject_ref` (relay).
</ResponseField>

<ResponseField name="agent" type="object">
  <Expandable defaultOpen title="properties">
    <ResponseField name="name" type="string">
      Display name of the published agent on this thread.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message_count" type="integer">
  Number of messages on the thread. List only.
</ResponseField>

<ResponseField name="last_message" type="object">
  Most recent message, content truncated to 120 characters. List only.
</ResponseField>

<ResponseField name="pending_elicitation" type="object">
  Present when a run is `awaiting_input`.

  <Expandable title="properties">
    <ResponseField name="run_id" type="uuid">
      The paused run.
    </ResponseField>

    <ResponseField name="kind" type="string">
      Patch that asked the question.
    </ResponseField>

    <ResponseField name="prompt" type="object">
      Arguments the agent sent with the question.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pending_action" type="object">
  Present when a run is `awaiting_outcome`.

  <Expandable title="properties">
    <ResponseField name="run_id" type="uuid">
      The waiting run.
    </ResponseField>

    <ResponseField name="tool_call_id" type="uuid">
      The proposed action to resolve.
    </ResponseField>

    <ResponseField name="patch_ref" type="string">
      Patch that proposed the action.
    </ResponseField>

    <ResponseField name="args" type="object">
      Arguments the agent sent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="timestamp">
  When the thread was opened.
</ResponseField>

<ResponseField name="updated_at" type="timestamp">
  When the thread last changed.
</ResponseField>

## Endpoints

* [Create a thread](/api-reference/loom/create-a-thread) — `POST /v1/loom/threads`
* [List threads](/api-reference/loom/list-threads) — `GET /v1/loom/threads`