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

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"}
  }'

crewship thread create dep_abc123 --metadata '{"user_id": "user_1"}'

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.

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?"}
  }'

crewship invoke dep_abc123 --thread thr_abc123 -i '{"message": "Hello"}'

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:

curl https://api.crewship.dev/v1/threads/thr_abc123/history \
  -H "Authorization: Bearer YOUR_API_KEY"

Managing Threads

# 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

Streaming

Real-time event streaming from runs

API Reference

Threads API docs

Getting Started

CLI Reference

Configuration

Guides

What are Threads?

Key Concepts

Creating a Thread

Running in a Thread

Concurrency

Thread History

Managing Threads

Streaming

API Reference

​What are Threads?

​Key Concepts

​Creating a Thread

​Running in a Thread

​Concurrency

​Thread History

​Managing Threads

​Related

Streaming

API Reference

What are Threads?

Key Concepts

Creating a Thread

Running in a Thread

Concurrency

Thread History

Managing Threads

Related