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

# Three curls

> The smallest complete integration: open a thread, say something, read the reply.

Needs an API key and a published agent. Nothing else — no connection, no keypair, no endpoint of your own.

```bash theme={null}
export PW_KEY="sk_live_..."
export PW_AGENT="agent_4f3c..."
export PW_SUBJECT="user_9f2"
export PW_BASE="https://api.usepatchwork.co/v1/loom"
```

## The script

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

auth=(-H "Authorization: Bearer $PW_KEY"
      -H "Patchwork-Subject: $PW_SUBJECT"
      -H "Content-Type: application/json")

# 1. Open a thread.
thread=$(curl -sS -X POST "${auth[@]}" "$PW_BASE/threads" \
  -d "{\"agent\": \"$PW_AGENT\"}" | jq -r '.data.id')
echo "thread: $thread"

# 2. Say something.
run=$(curl -sS -X POST "${auth[@]}" "$PW_BASE/threads/$thread/messages" \
  -d '{"content": "What can you help me with?"}' | jq -r '.data.run_id')
echo "run: $run"

# 3. Poll until the run is terminal.
while :; do
  body=$(curl -sS "${auth[@]}" "$PW_BASE/runs/$run")
  state=$(echo "$body" | jq -r '.data.state')
  [[ $(echo "$body" | jq -r '.data.terminal') == "true" ]] && break
  echo "  … $state"
  sleep 1
done

echo "$body" | jq -r '.data.message.content'
```

## Handling a pause

The loop above exits on `closed` **or** `failed`. A real client also has to handle a run that stops and waits — `awaiting_input` is not terminal, so the loop would spin forever.

Poll the thread list instead, which tells you *why* it paused:

```bash theme={null}
pending=$(curl -sS "${auth[@]}" "$PW_BASE/threads" \
  | jq --arg t "$thread" '.data[] | select(.id == $t)')

echo "$pending" | jq '{
  elicitation: .pending_elicitation,
  confirmation: .pending_confirmation,
  action:       .pending_action
}'
```

At most one is ever set. Answer a question by posting a message; resolve the other two with [confirm](/examples/approving-writes) or [outcome](/examples/outcomes).

## Reusing the thread

Keep the thread id. The same subject talking to the same agent should reuse it — that is what gives a returning user their history. Start a new thread when the conversation should start clean.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.