Skip to navigation
Machines

Machines quickstart

Beta
Lint a procedure, save it, run it and send the tool outputs.
View as Markdown

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.

1

Set the key and the host

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"
2

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.

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
3

Lint the procedure

A lint costs nothing and saves nothing.

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}'
{ "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.

4

Save the first version

The first version of a Machine is published.

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}'
{
"name": "invoice-intake",
"version": 1,
"published": true,
"caller_tools": [
{ "name": "erp_find_vendor", "effect": "read" },
{ "name": "erp_post_invoice", "effect": "irreversible" }
]
}
5

Start a run

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:

{
"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"
}
]
}
}
6

Send the output of the vendor lookup

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

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:

{
"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."}}.

7

Send the output of the post

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}'
{ "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.

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.

Next steps