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

# Requests

> Some products can't answer in one round trip. They hand you a request id, do the work off the request, and let you wait, poll, or catch a webhook.

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](/guides/extract) is the first Workbench product to use it, and Loom [runs](/guides/runs) already work the same way. Learn it once.

## The shape

<Steps>
  <Step title="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).
  </Step>

  <Step title="Find out when it's done">
    Poll `GET /v1/requests/:id`, or catch the `request.completed` / `request.failed` webhook.
  </Step>

  <Step title="Read the result">
    A completed request carries its result; a failed one carries an error.
  </Step>
</Steps>

**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`.

| `wait` | Behavior |
| - | - |
| omitted, `false`, `0` | Return `202` immediately. |
| present, `true`, `1` | Hold until the work finishes **or** the wait deadline. |
| a number, e.g. `wait=15` | Same, but hold at most `min(15s, deadline)`. |

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.

```bash theme={null}
# fire and forget — 202 now
curl -X POST https://api.usepatchwork.co/v1/extract \
  -H "Authorization: Bearer $PATCHWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

# hold for a quick answer — 200 if it lands in time, else 202
curl -X POST "https://api.usepatchwork.co/v1/extract?wait=15" \
  -H "Authorization: Bearer $PATCHWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

<Note>
  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.
</Note>

## Polling

```bash theme={null}
curl https://api.usepatchwork.co/v1/requests/req_8f2c... \
  -H "Authorization: Bearer $PATCHWORK_API_KEY"
```

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "req_8f2c...",
    "product": "extract",
    "state": "completed",
    "result": { "…": "product-specific result" }
  }
}
```

`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](/api-reference/webhook-endpoint). The `data` is the same object the poll returns, so a caller who already `wait`ed and got a `200` still gets the webhook — **dedupe on `id`**.

## Two clocks

| Clock | Value | What it bounds |
| - | - | - |
| Wait deadline | 25s | How long a `wait` request holds the HTTP connection. |
| Job deadline | 120s | How long the work itself may run before it's marked `failed`. |

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](/api-reference/request) for the exact shapes.


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