Run several capabilities over one set of files

Runs several capabilities over one set of files in a single call.

Every file is parsed once, then each step runs over the parsed set — in parallel, not chained. A step never consumes another step’s output.

A step is one of:

{ "extract": {…} }, { "redact": {…} }, { "fill": {…} }, { "sign": {…} } — the same inline config the matching verb takes.
{ "action": "act_… | slug", "params": {…} } — a saved action.

There is no parse step: parsing is automatic.

Always asynchronous. The response is 202 carrying the run id and one {id, capability} per step. Poll the run — its steps[] reports each step’s status and result under the id you were handed at create.

{
  "files": [{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }],
  "steps": [
    { "extract": { "schema": { "type": "object", "properties": { "business_name": { "type": ["string", "null"] } } } } },
    { "redact": { "mode": "targeted" } }
  ]
}

Learn more: Pipeline guide

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

fileslist of objectsRequired

The input files, up to 100. They are parsed once and every step sees the same parsed set.

stepslist of objectsRequired

What to run over the files — up to 20 steps, executed in parallel rather than chained.

Each step is either an inline capability config ({ "extract": {…} }, { "redact": {…} }, { "fill": {…} }, { "sign": {…} }) or a saved action ({ "action": "…", "params": {…} }). There is no parse step: parsing is automatic. A step never consumes another step's output.

metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run's events, given one of two ways.

{ "url": "…" } — a one-off https endpoint for this run only.
{ "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

ttlintegerOptional1-604800Defaults to 86400

How long, in seconds, to keep this run and its files before purging them automatically.

The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.

E-signature runs are exempt — an envelope waits for its signers however long that takes.

Response

Accepted.

object"pipeline_run"

idstring

statusenum

Where the run is in its life.

Status	Meaning
`queued`	Accepted, not started
`processing`	Work in flight
`needs_input`	Waiting for an external action, such as an e-signature
`processed`	Finished; `output` is populated
`failed`	Finished unsuccessfully
`cancelled`	Stopped on request
`expired`	TTL elapsed and the data was purged

The last four are terminal.

statusUrlstring

stepslist of objects

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error