Skip to main content
Relay is for channels Patchwork does not render. Your backend is the caller. The user never talks to Patchwork directly.
Same agents, same traces, same patches as direct. Different credential.

​
Authenticate

Use a workspace secret key. Identify the end user with a header — do not put a user id in the URL.
​
string
required
Bearer plus a workspace secret (sk_…).
​
string
required
Stable id for the person in this channel. Prefix by channel so Slack and WhatsApp users do not collide: slack:U0APP, wa:15551234567.
​
string
Connection id or name. Sets which host tools this call uses. Required when the agent has unpinned customer tools.
You can also pass subject_ref in the create-thread body. The header wins if both are present.
The workspace key is a secret. It lives on your server. If it leaks, rotate it in the dashboard.

​
Post a message

202 with a run_id. Your backend waits for the run — poll or subscribe — then writes the assistant’s reply back to Slack (or WhatsApp, or email).

​
When the agent asks a question

The run enters awaiting_input. Collect the user’s next message in your channel, then POST it to the same thread. The run resumes.

​
When the agent calls a tool you host

The run enters awaiting_outcome. Confirm the side effect:
state is occurred or failed. The agent continues from there. Verifying the tool call itself is identical in both modes — Patchwork-Signature over your request secret, plus the subject token. See Signing and verification.

​
Confirm your setup

Host /patchwork/up as described in Signing and verification, then press Test on the connection. It proves your request secret matches — a bare ok can’t pass. This applies to any minted connection, relay or direct.

​
Subject tokens (mint URL)

When a run needs a subject token to call your tools, Patchwork POSTs to the connection’s mint_url. The request is presenter-signed, and the response must be a bare { token, expires_in } — see The mint endpoint.
Verify the signature, then return a short-lived token for that user:
Your backend never forwards a token in the Loom request body. The API key names the workspace; Patchwork-Subject names the subject — an opaque id you choose, which we never resolve.

​
Thread identity

Threads are scoped to the subject. The same Slack user talking to the same agent reuses their thread. A different string is a different subject, with its own threads and its own memory. Never put emails or phone numbers in Patchwork-Subject — the value is stored verbatim, returned in responses, and written to logs. Use the channel’s stable id, and prefix it by source. See Subjects for composing ids across tenants.