> 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 quickstart

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

This page saves a Machine that posts a supplier invoice to an ERP, then runs it. Your system is the ERP: you send the output of each tool call by hand. You need `curl`, `jq` and an API key with the scopes `machines` and `machines:write`. Read [API keys](/paperwork/v2/keys).

#### Set the key and the host

```bash
export CRK_SLUG="acme"                # the slug of your organization
export CRK_API_KEY="crk_test_acme_…"  # a key with machines and machines:write
export CRK_API="https://$CRK_SLUG.cloudraker.run/v2"
```

#### Write the procedure and the tools

The procedure finds the vendor, then posts the invoice. The post is `irreversible`, so it has `"limit": 1` and a check before it.

```bash
cat > procedure.json <<'EOF'
{
  "language": "bm-procedure/2",
  "procedure": "invoice-intake",
  "description": "Post a supplier invoice to the ERP.",
  "inputs": {
    "tax_id": { "type": "string" },
    "invoice_number": { "type": "string" },
    "total": { "type": "number" }
  },
  "steps": [
    {
      "id": "vendor",
      "tool": "erp_find_vendor",
      "args": { "tax_id": "@input.tax_id" },
      "on_error": {
        "cases": [
          {
            "code": "vendor_not_found",
            "then": { "finish": "refused", "report": "No vendor has the tax id {{@input.tax_id}}." }
          }
        ]
      }
    },
    {
      "id": "post",
      "tool": "erp_post_invoice",
      "limit": 1,
      "require": [{ "check": "args.amount > 0 && args.amount <= 50000", "message": "the total is from 0 to 50,000" }],
      "args": {
        "vendor_id": "@vendor.vendor_id",
        "invoice_number": "@input.invoice_number",
        "amount": "@input.total"
      }
    }
  ],
  "finish": { "status": "done", "report": "Invoice {{@input.invoice_number}} is posted as {{@post.document_id}}." }
}
EOF

cat > tools.json <<'EOF'
[
  {
    "name": "erp_find_vendor",
    "description": "Find a vendor by its tax id.",
    "inputSchema": { "type": "object", "properties": { "tax_id": { "type": "string" } }, "required": ["tax_id"] },
    "outputSchema": {
      "type": "object",
      "properties": { "vendor_id": { "type": "string" }, "name": { "type": "string" } },
      "required": ["vendor_id", "name"]
    },
    "annotations": { "readOnlyHint": true },
    "x-errors": {
      "vendor_not_found": {
        "type": "object",
        "properties": { "code": { "const": "vendor_not_found" }, "message": { "type": "string" } }
      }
    }
  },
  {
    "name": "erp_post_invoice",
    "description": "Post an invoice in the ERP.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "vendor_id": { "type": "string" },
        "invoice_number": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["vendor_id", "invoice_number", "amount"]
    },
    "outputSchema": {
      "type": "object",
      "properties": { "document_id": { "type": "string" } },
      "required": ["document_id"]
    },
    "x-effect": "irreversible"
  }
]
EOF
```

#### Lint the procedure

A lint costs nothing and saves nothing.

```bash
jq -n --slurpfile p procedure.json --slurpfile t tools.json '{procedure: $p[0], tools: $t[0]}' \
  | curl -s -X POST "$CRK_API/machines/lint" \
      -H "Authorization: Bearer $CRK_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- | jq '{ok, diagnostics}'
```

```json
{ "ok": true, "diagnostics": [] }
```

Remove `"limit": 1` from the step `post` and lint again. The answer is still `200`, with `ok: false` and the diagnostic `irreversible-limit`. Read the [lint codes](/paperwork/v2/machines-language#lints).

#### Save the first version

The first version of a Machine is published.

```bash
jq -n --slurpfile p procedure.json --slurpfile t tools.json '{procedure: $p[0], tools: $t[0]}' \
  | curl -s -X POST "$CRK_API/machines/invoice-intake/versions" \
      -H "Authorization: Bearer $CRK_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- | jq '{name, version, published, caller_tools}'
```

```json
{
  "name": "invoice-intake",
  "version": 1,
  "published": true,
  "caller_tools": [
    { "name": "erp_find_vendor", "effect": "read" },
    { "name": "erp_post_invoice", "effect": "irreversible" }
  ]
}
```

#### Start a run

```bash
curl -s -X POST "$CRK_API/machines/invoice-intake/runs" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d '{ "inputs": { "tax_id": "CA-123", "invoice_number": "INV-1001", "total": 1250 } }' \
  | tee run.json | jq '{id, status, required_action}'
```

The run stops at the first tool call. The answer is `202` with a job in `needs_input`:

```json
{
  "id": "job_01JC3X…",
  "status": "needs_input",
  "required_action": {
    "type": "tool_calls",
    "tool_calls": [
      {
        "id": "mc_01JC3X…_2",
        "name": "erp_find_vendor",
        "arguments": { "tax_id": "CA-123" },
        "idempotency_key": "job_01JC3X…:0:",
        "effect": "read",
        "deadline_at": "2026-11-10T14:12:11Z"
      }
    ]
  }
}
```

#### Send the output of the vendor lookup

Your system finds the vendor. Send the output with the id of the tool call:

```bash
RUN=$(jq -r .id run.json)
CALL=$(jq -r '.required_action.tool_calls[0].id' run.json)

curl -s -X POST "$CRK_API/machines/runs/$RUN/tool-outputs" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d "{ \"tool_outputs\": [{ \"tool_call_id\": \"$CALL\", \"output\": { \"vendor_id\": \"V-19\", \"name\": \"Acme Supply\" } }] }" \
  | tee run.json | jq '{status, required_action}'
```

The answer is the run at its next stop. It waits for the post:

```json
{
  "status": "waiting",
  "required_action": {
    "type": "tool_calls",
    "tool_calls": [
      {
        "id": "mc_01JC3X…_6",
        "name": "erp_post_invoice",
        "arguments": { "vendor_id": "V-19", "invoice_number": "INV-1001", "amount": 1250 },
        "idempotency_key": "job_01JC3X…:1:",
        "effect": "irreversible",
        "deadline_at": "2026-11-10T14:12:13Z"
      }
    ]
  }
}
```

To see the refusal path, send an error output instead: `{"tool_call_id": "…", "is_error": true, "output": {"code": "vendor_not_found", "message": "No vendor."}}`.

#### Send the output of the post

```bash
CALL=$(jq -r '.required_action.tool_calls[0].id' run.json)

curl -s -X POST "$CRK_API/machines/runs/$RUN/tool-outputs" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d "{ \"tool_outputs\": [{ \"tool_call_id\": \"$CALL\", \"output\": { \"document_id\": \"DOC-88\" } }] }" \
  | jq '{status, outcome, report}'
```

```json
{ "status": "done", "outcome": "done", "report": "Invoice INV-1001 is posted as DOC-88." }
```

The job is `succeeded`. Read it with `GET /v2/jobs/{id}`: `output` holds the result and `usage` holds the credits.

## The same loop in TypeScript

This script runs the Machine and answers each tool call with a function of your system. It uses `fetch` only, so it runs in Node 20 or later, Bun, Deno and Cloudflare Workers.

```ts
const api = `https://${process.env.CRK_SLUG}.cloudraker.run/v2`
const headers = {
  Authorization: `Bearer ${process.env.CRK_API_KEY}`,
  'Content-Type': 'application/json',
  Prefer: 'wait=30',
}

type ToolCall = { id: string; name: string; arguments: Record<string, unknown> }
type Output = { output: unknown; is_error?: boolean }

// Your system. Each tool of the Machine has one function.
const tools: Record<string, (args: Record<string, unknown>) => Promise<Output>> = {
  async erp_find_vendor(args) {
    if (args.tax_id !== 'CA-123') {
      return { is_error: true, output: { code: 'vendor_not_found', message: 'No vendor.' } }
    }
    return { output: { vendor_id: 'V-19', name: 'Acme Supply' } }
  },
  async erp_post_invoice() {
    return { output: { document_id: 'DOC-88' } }
  },
}

async function call(path: string, body?: unknown) {
  const res = await fetch(`${api}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (res.status >= 400) {
    throw new Error(`${res.status} ${await res.text()}`)
  }
  return res.json()
}

const job = await call('/machines/invoice-intake/runs', {
  inputs: { tax_id: 'CA-123', invoice_number: 'INV-1001', total: 1250 },
})
let run = await call(`/machines/runs/${job.id}`)

const ended = ['succeeded', 'failed', 'cancelled', 'expired']
while (!ended.includes(run.job_status)) {
  const action = run.required_action
  if (action?.type === 'tool_calls') {
    const outputs = await Promise.all(
      action.tool_calls.map(async (c: ToolCall) => ({ tool_call_id: c.id, ...(await tools[c.name]!(c.arguments)) })),
    )
    run = await call(`/machines/runs/${run.id}/tool-outputs`, { tool_outputs: outputs })
  } else if (action === null) {
    // The engine runs steps. Wait for the next stop.
    run = await call(`/machines/runs/${run.id}`)
  } else {
    // An answer of a person or a later input. This script does not handle them.
    throw new Error(`The run waits for ${action.type}.`)
  }
}

// A failed job has run.error. A procedure end has run.outcome and run.report.
console.log(run.job_status, run.outcome, run.report)
```

A tool call can arrive again, for example after a timeout. Use `idempotency_key` as the idempotency key of your system. It is the same for each attempt of a step. Use the tool call `id` only when each attempt must run. Read [Run a tool call](/paperwork/v2/machines#run-a-tool-call).

## Next steps

* Learn the run loop, holds and inputs: [Machines](/paperwork/v2/machines).
* Write your own procedure: [Machine language](/paperwork/v2/machines-language).
* Run the Machine from an OpenAI SDK: [OpenAI compatible API](/paperwork/v2/machines-openai).
* Get the `needs_input` events in the background: [Webhooks](/paperwork/v2/webhooks).