> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Machines

> **Note**
>
> Machines are in beta. The routes, the objects and the language can change before general
> availability.

A **Machine** is a procedure that the API compiles into a fixed program. The engine runs the program step by step. It writes each step to a log before it does the step. No AI model chooses the next step.

Use a Machine for a process that must run the same way each time: invoice intake, vendor onboarding, a claim check. Your system runs the tool calls of the Machine. A person answers the questions that the procedure cannot settle.

* Start with the [Machines quickstart](/paperwork/v2/machines-quickstart).
* Write a procedure with the [Machine language](/paperwork/v2/machines-language).
* Run a Machine from an OpenAI SDK with the [OpenAI compatible API](/paperwork/v2/machines-openai).

## Concepts

| Term              | Meaning                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Procedure         | A JSON document (`bm-procedure/2`) with the inputs, the steps and the report. Read the [Machine language](/paperwork/v2/machines-language). |
| Tool list         | The tools that the steps call, in the MCP tool shape, with their input and output schemas.                                                  |
| Caller tool       | A tool of your tool list. The run stops, and your system runs the call and sends the output.                                                |
| Paperwork tool    | A `file_*` tool, for example `file_extract`. The engine runs it with the Paperwork API. It bills as a Paperwork call.                       |
| Effect            | `read`, `write` or `irreversible`. The engine retries, holds and checks a step by its effect.                                               |
| Version           | A compiled procedure with its tools. A version never changes.                                                                               |
| Published version | The version that a run with no `version` runs.                                                                                              |
| Run               | One run of a version, or of an inline procedure. A run is a [job](/paperwork/v2/jobs): the run id is the job id.                            |
| Ladder            | The answerers of a step that needs judgment, in a fixed order: a decision model, the exception model, then a person.                        |

## Scopes

| Scope            | Routes                                                                                  |
| ---------------- | --------------------------------------------------------------------------------------- |
| `machines`       | Each route of this page: lint, read, run, send outputs and answers, cancel.             |
| `machines:write` | Also needed to save a version, to publish a version and to delete a Machine.            |
| `jobs:read`      | With `machines`, read the runs that another credential of the same environment started. |

Test keys can lint, save and run Machines. Their runs use real credits. Read [API keys](/paperwork/v2/keys).

## Check a procedure

`POST /v2/machines/lint` compiles a procedure with its tools. It saves nothing and costs nothing.

```json
{ "procedure": { "language": "bm-procedure/2", "...": "..." }, "tools": [], "strict": false, "include_ir": false }
```

The answer is `200`, also when the procedure has errors:

```json
{
  "object": "machine_lint",
  "ok": false,
  "ir_hash": null,
  "diagnostics": [
    {
      "level": "error",
      "code": "ref-path",
      "path": "steps[1].args.vendor_id",
      "message": "@vendor.id: erp_find_vendor returns no such path: vendor.id has no key \"id\". Keys: vendor_id, name"
    }
  ],
  "summary": { "steps": 2, "tools": ["erp_find_vendor", "erp_post_invoice"], "effects": { "read": 1, "write": 0, "irreversible": 1 }, "inputs": {} },
  "ir": null
}
```

`strict: true` makes each warning an error. `include_ir: true` adds the compiled program when `ok` is true. Read the [lint codes](/paperwork/v2/machines-language#lints).

## Save versions

`POST /v2/machines/{name}/versions` compiles the procedure and saves it as the next version.

* A name has 1 to 63 characters: lower case letters, digits and hyphens. It starts with a letter or a digit. `runs` and `lint` are reserved.
* The first version of a Machine creates the Machine, and is published. A later version is a draft until you publish it: send `"publish": true`, or call `POST /v2/machines/{name}/versions/{version}/publish`.
* A procedure with errors gives [`400 procedure_invalid`](/paperwork/v2/errors#procedure_invalid) with `details.diagnostics`. The API saves nothing.
* A save of the same procedure and tools as the latest version saves nothing. The answer is `200` with that version. A new version answers `201`.
* `base_version` protects against two writers. When it is not the latest version, the answer is [`409 version_conflict`](/paperwork/v2/errors#version_conflict) with `details.latest_version`.
* Version numbers never repeat, also after a delete.

```json
{
  "object": "machine_version",
  "name": "invoice-intake",
  "version": 2,
  "published": false,
  "ir_hash": "sha256:6af76865c1d0…",
  "source_hash": "sha256:91c2…",
  "compiler": "@crk-lib/machines@0.1.0",
  "inputs": { "tax_id": { "type": "string" }, "invoice_number": { "type": "string" }, "total": { "type": "number" } },
  "caller_tools": [
    { "name": "erp_find_vendor", "effect": "read" },
    { "name": "erp_post_invoice", "effect": "irreversible" }
  ],
  "warnings": [],
  "created_at": "2026-11-10T14:02:11Z",
  "created_by": "key:key_01JC9M…"
}
```

`GET /v2/machines/{name}/versions/{version}?include=procedure,tools,ir` adds the source, the tools and the compiled program. `GET /v2/machines` lists the Machines. `GET /v2/machines/{name}/versions` lists the versions, newest first. Both take `cursor` and `limit` (1 to 100).

`DELETE /v2/machines/{name}` deletes a Machine and all its versions. Runs that started continue.

## Start a run

`POST /v2/machines/{name}/runs` starts a run of a saved Machine. `POST /v2/machines/runs` compiles an inline procedure and runs it, with no saved Machine.

```http
POST /v2/machines/invoice-intake/runs
Prefer: wait=30
Idempotency-Key: 9f1c2b7e-…

{
  "version": 2,
  "inputs": { "tax_id": "CA-123", "invoice_number": "INV-1001", "total": 1250 },
  "options": { "exception_model": "default", "caller_timeout_s": 600 },
  "notify": { "endpoint": "whe_…" },
  "metadata": { "ticket": "A-1" }
}
```

| Field                            | Meaning                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `version`                        | Saved runs only. With no `version`, the run uses the published version.                                       |
| `procedure`, `tools`             | Inline runs only. A procedure with errors gives `400 procedure_invalid` and no job.                           |
| `inputs`                         | The inputs that the procedure declares. A file input is `{"url": "https://…", "name": "…"}` or `{"id": "…"}`. |
| `options.exception_model`        | `default`, or `off`: each model rung goes to the next rung.                                                   |
| `options.caller_timeout_s`       | The seconds that your system has for each tool call: 60 to 86,400. Default 600.                               |
| `notify`, `deadline`, `metadata` | The job fields. Read [Jobs](/paperwork/v2/jobs) and [Webhooks](/paperwork/v2/webhooks).                       |

The answer is a Job with the capability `machines`. The API holds the request until the run stops, up to the `Prefer: wait` time (default 30 seconds). The answer is `200` when the job ended, else `202`. Read [Sync and async](/paperwork/v2/sync-and-async).

An unknown Machine or version gives [`404 not_found`](/paperwork/v2/errors#not_found). Too many active runs give [`429 concurrency_limited`](/paperwork/v2/errors#concurrency_limited). The API creates no job for these answers. An `Idempotency-Key` applies to both run start routes. Read [Idempotency](/paperwork/v2/idempotency).

## The run loop

A run stops each time it needs something from outside: the output of a caller tool, the answer of a person, or a later input. The job is then `needs_input`, and `required_action` says what the run waits for.

1. Start the run.
2. Read `required_action`: in the Job of the answer, in the `job.needs_input` webhook or stream event, or with `GET /v2/machines/runs/{id}`. After a resume, the fresh action is in the resume answer.
3. Do the action: run the tool call, get the answer of a person, or get the input.
4. Send the result to the run. The answer is the run at its next stop, with its next `required_action`.
5. Do steps 2 to 4 again until the job ends.

After a resume, use the run of the resume answer. Do not read the job again for the next action. The job can show the earlier `needs_input` and the earlier action for a short time after the run continues. A second send of the same output gives no error, so a loop that reads the job can run one tool call two times. If the answer is `running` (the wait ended first), read the run with `GET /v2/machines/runs/{id}` and `Prefer: wait=30`.

### The required action

```json
{
  "type": "tool_calls",
  "tool_calls": [
    {
      "id": "mc_01JC3X5Q8ZKX4T9V0R2H7N6M3B_2",
      "name": "erp_find_vendor",
      "arguments": { "tax_id": "CA-123" },
      "idempotency_key": "job_01JC3X5Q8ZKX4T9V0R2H7N6M3B:0:",
      "effect": "read",
      "deadline_at": "2026-11-10T14:12:11Z"
    }
  ]
}
```

| `type`       | The run waits for                                                             | Send it with                               |
| ------------ | ----------------------------------------------------------------------------- | ------------------------------------------ |
| `tool_calls` | The output of a call of a caller tool.                                        | `POST /v2/machines/runs/{id}/tool-outputs` |
| `answer`     | The answer of a person: `{seq, code, reason, question, schema, attachments}`. | `POST /v2/machines/runs/{id}/answers`      |
| `inputs`     | A later input, for example a second message: `{name, schema}` per input.      | `POST /v2/machines/runs/{id}/inputs`       |

`required_action` is `null` when the run waits for nothing. A very large action can come with `arguments_truncated: true` or `attachments_truncated: true`. Then read the full action with `GET /v2/machines/runs/{id}`.

### Run a tool call

Run the call in your system, then send its output:

```http
POST /v2/machines/runs/job_01JC3X…/tool-outputs
Prefer: wait=30

{ "tool_outputs": [{ "tool_call_id": "mc_01JC3X…_2", "output": { "vendor_id": "V-19", "name": "Acme Supply" } }] }
```

* The output must match the `outputSchema` of the tool. A mismatch gives `400 invalid_request` with `details.issues`, and the call stays pending.
* An error output has `"is_error": true` and `"output": {"code", "message", "retryable"?}`. A `code` from the `x-errors` of the tool matches an `on_error` case of the step. Another code goes to the `else` of the step. `retryable: true` marks a transient error.
* `idempotency_key` is the same for each attempt of one step, also for a retry with changed arguments. To run each attempt, use the tool call `id` as your key.
* After `deadline_at`, the engine treats the call as a timeout. A `read` step can call again. A `write` step holds with the code `unknown_outcome`, because the call can have run.
* A second send of an output that the run already took changes nothing. The answer is the current run, so a retry is safe.

### Answer a hold

An ask with the rung `person` stops the run with a hold that can resume. Show `question` and `attachments` to a person, then send a value that matches `schema`:

```http
POST /v2/machines/runs/job_01JC3X…/answers

{ "seq": 23, "value": "FEE-DAMAGE" }
```

A value that does not match `schema` gives `400 invalid_request`, and the hold stays open.

### Send an input

```http
POST /v2/machines/runs/job_01JC3X…/inputs

{ "name": "user_message2", "value": "The second part of the request." }
```

A file input takes `{"url": "https://…"}` or `{"id": "…"}`.

### Who can resume a run

Only the credential that started the run can send outputs, answers and inputs, and cancel it. Another credential gets `404 job_not_found`. A resume costs credits later, so the billing block applies: with no credits, the answer is [`402 credits_exhausted`](/paperwork/v2/errors#credits_exhausted).

A send for a call, a hold or an input that the run does not wait for gives [`409 not_waiting`](/paperwork/v2/errors#not_waiting). `details.reason` is `call_not_pending`, `hold_not_open`, `input_not_awaited` or `run_ended`, and `details.required_action` is what the run waits for now.

Each resume route waits for the next stop of the run, as `Prefer: wait=N` says (1 to 90, default 30). The answer is the run.

## The run object

`GET /v2/machines/runs/{id}` reads a run and what it waits for. `Prefer: wait=N` (1 to 90) holds the request until the run stops.

```json
{
  "object": "machine_run",
  "id": "job_01JC3X…",
  "machine": "invoice-intake",
  "version": 2,
  "ir_hash": "sha256:6af76865c1d0…",
  "job_status": "needs_input",
  "status": "waiting",
  "outcome": null,
  "required_action": { "type": "tool_calls", "tool_calls": [] },
  "report": null,
  "hold": null,
  "diverged": null,
  "error": null,
  "entries": 4,
  "usage": { "model_calls": 0, "decide_calls": 0, "prompt_tokens": 0, "completion_tokens": 0 },
  "created_at": "2026-11-10T14:02:11Z",
  "ended_at": null
}
```

| `status`                     | Job status            | Meaning                                                                       |
| ---------------------------- | --------------------- | ----------------------------------------------------------------------------- |
| `new`                        | `queued` or `running` | The run has not started its first step.                                       |
| `running`                    | `running`             | The engine runs steps, for example a Paperwork tool or a model call.          |
| `waiting`                    | `needs_input`         | The run waits for a tool output or an input.                                  |
| `held`, `outcome: null`      | `needs_input`         | The run waits for the answer of a person.                                     |
| `held`, `outcome: "held"`    | `succeeded`           | The run ended with a hold that cannot resume. Read [The result](#the-result). |
| `done`, `refused`, `aborted` | `succeeded`           | The procedure ended. `report` holds the report.                               |
| `error`                      | `failed`              | The engine failed. `error` holds the cause.                                   |
| `cancelled`                  | `cancelled`           | The credential that started the run cancelled it.                             |
| `expired`                    | `expired`             | The run did not end in 7 days.                                                |

`machine` and `version` are `null` for an inline run.

## The result

A procedure end is a succeeded job, also a refusal or a hold. `output` is the result:

```json
{
  "object": "machine_run_result",
  "run_id": "job_01JC3X…",
  "machine": "invoice-intake",
  "version": 2,
  "ir_hash": "sha256:6af76865c1d0…",
  "outcome": "done",
  "report": "Invoice INV-1001 is posted as DOC-88.",
  "entries": 9,
  "stats": { "model_calls": 0, "decide_calls": 0, "prompt_tokens": 0, "completion_tokens": 0, "paperwork_calls": 0 }
}
```

| `outcome` | Cause                                                                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `done`    | The run got to the end of the steps, or a `finish` step with `done`.                                                                                                                        |
| `refused` | A `finish` step with `refused`: a business refusal.                                                                                                                                         |
| `aborted` | A `finish` step with `aborted`. The engine ran the compensations.                                                                                                                           |
| `held`    | A hold that cannot resume: a `hold` step, or a hold of the engine (`unknown_outcome`, `repeat_write`, `too_many_items`). `hold` holds `{code, reason, attach}`. A person finishes the work. |

The machine name is `inline` in the result of an inline run. A report that is too large is cut, with `report_truncated: true`.

Only an engine fault fails the job, with the [job error code](/paperwork/v2/jobs#job-error-codes) `processing_failed`. `details.cause` is `engine_error`, `replay_diverged` or `log_limit`. Do not retry a run with `replay_diverged`: change the Machine or contact CloudRaker.

## Follow a run

* **Webhooks:** set `notify.endpoint` on the run start. The `job.needs_input` event carries the Job with `required_action`. Read [Webhooks](/paperwork/v2/webhooks).
* **Stream:** send `Accept: text/event-stream` on the run start or on `GET /v2/jobs/{id}`. Read [Streaming](/paperwork/v2/streaming).
* **Poll:** `GET /v2/machines/runs/{id}` with `Prefer: wait=N`.
* **List:** `GET /v2/jobs?capability=machines` lists the runs.
* **Log:** `GET /v2/machines/runs/{id}/log?after_seq=0&limit=100` reads the event log in seq order, up to 500 entries per page. Send `next_after_seq` to get the next page.

Each log entry has a `seq`, a `type` (for example `call.intent`, `call.result`, `ask.answer`, `hold`, `finish`), the step and its `data`.

## Cancel a run

`POST /v2/machines/runs/{id}/cancel` cancels the run and its job. `POST /v2/jobs/{id}/cancel` does the same. A cancel stops the run at its next action. It runs no compensation: the log lists the writes that are done, and a person decides. A run that ended gives [`409 job_not_cancellable`](/paperwork/v2/errors#job_not_cancellable).

## Limits

| Limit                          | Value                                         |
| ------------------------------ | --------------------------------------------- |
| Active runs of an organization | 20 with test keys, 500 with live keys         |
| Lifetime of a run              | 7 days, then the job is `expired`             |
| Storage of a run               | Deleted 30 days after the start, with the job |
| Body of a run start            | 4 MiB                                         |
| Inputs of a run                | 1 MiB                                         |
| One tool output                | 1 MiB                                         |
| Tool outputs in one request    | 16                                            |
| Log entries of a run           | 20,000. Then the run fails with `log_limit`.  |
| Machines of an organization    | 500                                           |
| Versions of a Machine          | 1,000                                         |

A size limit gives `400 invalid_request` with `details.limit`. The limits of a procedure are on the [language page](/paperwork/v2/machines-language#limits).

## Billing

| Event                  | Credits | When                                                  |
| ---------------------- | ------- | ----------------------------------------------------- |
| `machine_run`          | 2       | A run that ends with a succeeded job: each `outcome`. |
| `machine_model_calls`  | 2       | Each call of the exception model.                     |
| `machine_decide_calls` | 1       | Each call of the decision model.                      |

* Lint, save, list and read are free. Steps and tool calls of your system are free.
* A failed, cancelled or expired run costs nothing, also when model calls ran.
* Paperwork steps bill as Paperwork calls.
* The job `usage` shows the credits when the job ends.

## Errors

| Status | Code                                                              | Cause                                                              |
| ------ | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| 400    | [`procedure_invalid`](/paperwork/v2/errors#procedure_invalid)     | The procedure does not compile. `details.diagnostics` lists why.   |
| 400    | [`invalid_request`](/paperwork/v2/errors#invalid_request)         | A body, an input, an output or an answer is not valid, or a limit. |
| 402    | [`credits_exhausted`](/paperwork/v2/errors#credits_exhausted)     | A run start or a resume with no credits.                           |
| 404    | [`not_found`](/paperwork/v2/errors#not_found)                     | No Machine or version with this name.                              |
| 404    | [`job_not_found`](/paperwork/v2/errors#job_not_found)             | No run with this id, or the credential cannot use it.              |
| 409    | [`version_conflict`](/paperwork/v2/errors#version_conflict)       | `base_version` is not the latest version.                          |
| 409    | [`not_waiting`](/paperwork/v2/errors#not_waiting)                 | The run does not wait for this call, hold or input.                |
| 429    | [`concurrency_limited`](/paperwork/v2/errors#concurrency_limited) | The organization has too many active runs.                         |