# `Attio.Threads`
[🔗](https://github.com/sgerrand/ex_attio/blob/v0.2.0/lib/attio/threads.ex#L1)

Functions for managing comment threads on records and list entries.

A thread groups one or more comments and is attached to a parent record or
list entry. Creating a thread also creates its first comment. Use
`Attio.Comments` to manage individual comments within a thread.

Threads are immutable after creation: the API provides no update or delete
operations on threads themselves. To add further comments to an existing
thread, use `Attio.Comments`.

Requires the `comment:read` scope for read operations and
`comment:read-write` for mutations.

## Pagination

`list/2` returns a single page. `stream/2` lazily pages through all threads;
`stream_all/2` collects them into `{:ok, list}`. See `Attio` for an overview.

    client
    |> Attio.Threads.stream()
    |> Enum.to_list()

# `create`

```elixir
@spec create(Attio.Client.t(), map()) :: {:ok, map()} | {:error, term()}
```

Creates a new thread with an initial comment.

## Required attributes

  * `"record_id"` - ID of the record to attach the thread to.
  * `"format"` - Content format: `"plaintext"` or `"markdown"`.
  * `"content"` - Initial comment content.

# `get`

```elixir
@spec get(Attio.Client.t(), String.t()) :: {:ok, map()} | {:error, term()}
```

Gets a single thread by its ID, including all comments.

# `list`

```elixir
@spec list(
  Attio.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Lists threads. Returns one page.

## Options

  * `:limit` - Number of threads per page.
  * `:cursor` - Pagination cursor from a previous response.

# `stream`

```elixir
@spec stream(
  Attio.Client.t(),
  keyword()
) :: Enumerable.t()
```

Returns a lazy stream of all threads across all pages.

Accepts the same options as `list/2`. Raises `{:attio_stream_error, error}`
on API failure mid-stream. Use `stream_all/2` if you prefer a standard
`{:ok, list} | {:error, term()}` return value.

# `stream_all`

```elixir
@spec stream_all(
  Attio.Client.t(),
  keyword()
) :: {:ok, [map()]} | {:error, Attio.Error.t() | Exception.t()}
```

Fetches all threads across all pages and returns them as a list.

Accepts the same options as `list/2`. Returns `{:ok, [map()]}` on success
or `{:error, term()}` if any page request fails. Unlike `stream/2`, the
entire result set is loaded into memory.

## Example

    {:ok, threads} = Attio.Threads.stream_all(client)

---

*Consult [api-reference.md](api-reference.md) for complete listing*