Quick start - Patchwork

The shortest path to a live agent uses a workspace API key and three HTTP calls. You need no keypair, no JWKS document, no connection, and no endpoint of your own — those arrive later, when the agent needs to call your backend.

Get an API key

In the dashboard, open Developers and copy a secret key (sk_…). Keep it server-side.

Publish an agent

Follow Your first agent. You need its public id, which looks like agent_4f3c….An agent with no patches wired still works — every agent can ask questions and hand off out of the box.

Make the three calls below

1. Open a thread

A thread is one conversation, and it belongs to a subject — an opaque id you choose for whoever the agent is acting for.

curl -X POST https://api.usepatchwork.co/v1/loom/threads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Patchwork-Subject: user_9f2" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_4f3c..."}'

{
  "status": "success",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent": { "name": "Support assistant" },
    "subject_ref": "user_9f2"
  }
}

2. Say something

curl -X POST https://api.usepatchwork.co/v1/loom/threads/3fa85f64-.../messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Patchwork-Subject: user_9f2" \
  -H "Content-Type: application/json" \
  -d '{"content": "What can you help me with?"}'

{
  "status": "success",
  "data": {
    "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "state": "running"
  }
}

202. The turn is accepted, not finished — a run is the unit of work, and it is still going.

3. Read the reply

curl https://api.usepatchwork.co/v1/loom/runs/7c9e6679-... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Patchwork-Subject: user_9f2"

{
  "status": "success",
  "data": {
    "state": "closed",
    "terminal": true,
    "cost_credits": 0.08,
    "message": {
      "role": "assistant",
      "content": "I can help you track an order, start a return, or update your details.",
      "created_at": "2026-08-30T12:00:04Z"
    }
  }
}

Poll until terminal is true. That is your agent working.

A run can also stop and wait for you — with a question, or with a write that needs approval. Both show as awaiting_input, and both are resumed differently. See Runs and states.

Where to go next

You now have a conversation. What you probably want next is an agent that does something in your system, and a way to put it in front of real users.

Choose an integration

Relay from your backend, or direct from the browser.

Connect your backend

Patches

Wrap your endpoints as capabilities the agent can use.

Subjects

Get the isolation boundary right before you have real users.

​1. Open a thread

​2. Say something

​3. Read the reply

​Where to go next

Choose an integration

Connect your backend

Patches

Subjects

1. Open a thread

2. Say something

3. Read the reply

Where to go next