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_…). Leftover sk_test_ secrets still authenticate and spend the same workspace balance.
​
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 the same as direct: Patchwork-Signature over your request secret, plus the subject token.

​
Subject tokens (mint URL)

When a run needs a subject token to call your tools, Patchwork POSTs to your workspace mint_url. The request is presenter-signed.
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 person.

​
Thread identity

Threads are scoped to the subject. The same Slack user talking to the same agent reuses their thread. A different channel prefix is a different person. Do not put emails or phone numbers in Patchwork-Subject if you can avoid it. Use the channel’s stable user id.