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

# Threads

> Maintain conversation context across multiple runs with threads

## What are Threads?

Threads allow you to maintain stateful conversation context across multiple runs within a deployment. Each thread is scoped to a single deployment and tracks conversation history, state, and checkpoints.

This is modeled after LangGraph's Threads API and works with CrewAI, LangGraph Python, and LangGraph JS frameworks.

## Key Concepts

* **Thread**: A stateful conversation context scoped to a deployment
* **Thread State**: JSON values representing the current conversation state
* **Checkpoints**: Historical snapshots of thread state after each run
* **Thread Status**: `idle` (ready), `busy` (running), `interrupted`, or `error`

## Creating a Thread

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crewship.dev/v1/threads \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "deployment_id": "dep_abc123",
      "metadata": {"user_id": "user_1", "session": "chat"}
    }'
  ```

  ```bash CLI theme={null}
  crewship thread create dep_abc123 --metadata '{"user_id": "user_1"}'
  ```
</CodeGroup>

## Running in a Thread

When you create a run in a thread context, the runner receives the thread state and can update it after completion.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crewship.dev/v1/threads/thr_abc123/runs \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": {"message": "Hello, how are you?"}
    }'
  ```

  ```bash CLI theme={null}
  crewship invoke dep_abc123 --thread thr_abc123 -i '{"message": "Hello"}'
  ```
</CodeGroup>

## Concurrency

Only one run can execute in a thread at a time. If a thread is `busy`, new run requests will be rejected with a 409 status. Wait for the current run to complete before starting a new one.

## Thread History

Each run that updates thread state creates a checkpoint. You can view the history of state changes:

```bash theme={null}
curl https://api.crewship.dev/v1/threads/thr_abc123/history \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Managing Threads

```bash theme={null}
# List threads for a deployment
crewship thread list dep_abc123

# Get thread details
crewship thread get thr_abc123

# Copy a thread (duplicate state)
crewship thread copy thr_abc123

# Delete a thread
crewship thread delete thr_abc123
```

## Related

<CardGroup cols={2}>
  <Card title="Streaming" icon="stream" href="/guides/streaming">
    Real-time event streaming from runs
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/threads/create">
    Threads API docs
  </Card>
</CardGroup>