Skip to main content

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

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

​
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