Skip to main content
Most Workbench calls answer inline — you POST, you get the result. Some can’t: reading a document takes seconds, not milliseconds. For those, Patchwork accepts the call, returns a request id, and does the work off the request. This is a shared convention, not a per-product quirk. Extract is the first Workbench product to use it, and Loom runs already work the same way. Learn it once.

​
The shape

1

Call it

The POST returns 202 Accepted with a request id and state: "pending" — unless you asked to wait and it finished in time (see below).
2

Find out when it's done

Poll GET /v1/requests/:id, or catch the request.completed / request.failed webhook.
3

Read the result

A completed request carries its result; a failed one carries an error.
Polling is the source of truth. The webhook is a fast path. Deliver-once webhooks can be missed or retried, so reconcile with a poll — never treat the webhook as the only signal.

​
Waiting

By default we return 202 the moment the work is queued and you find out the result later. If you’d rather hold the connection open for a quick answer, pass wait. If the work finishes inside the hold, you get 200 with the result directly. If the deadline passes first, you get the same 202 you’d have gotten with no wait — and the work keeps going. The wait deadline never cancels anything.
The wait deadline is 25 seconds, a platform constant that sits under typical proxy idle timeouts. A client cannot hold a worker open indefinitely — ask for wait=120 and you still get the id at 25s.

​
Polling

state is one of pending, completed, or failed. A completed request carries result; a failed one carries error with a code and message. A request id from another workspace is a 404.

​
Webhooks

When a request lands we fire request.completed or request.failed to your webhook endpoint. The data is the same object the poll returns, so a caller who already waited and got a 200 still gets the webhook — dedupe on id.

​
Two clocks

They’re independent: hitting the wait deadline hands you the id and leaves the work running; hitting the job deadline fails the request. See The Request object for the exact shapes.