Skip to navigation
Machines

Machines

Beta
Compiled procedures that run the same way each time. Your system runs the tool calls.
View as Markdown

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.

Concepts

TermMeaning
ProcedureA JSON document (bm-procedure/2) with the inputs, the steps and the report. Read the Machine language.
Tool listThe tools that the steps call, in the MCP tool shape, with their input and output schemas.
Caller toolA tool of your tool list. The run stops, and your system runs the call and sends the output.
Paperwork toolA file_* tool, for example file_extract. The engine runs it with the Paperwork API. It bills as a Paperwork call.
Effectread, write or irreversible. The engine retries, holds and checks a step by its effect.
VersionA compiled procedure with its tools. A version never changes.
Published versionThe version that a run with no version runs.
RunOne run of a version, or of an inline procedure. A run is a job: the run id is the job id.
LadderThe answerers of a step that needs judgment, in a fixed order: a decision model, the exception model, then a person.

Scopes

ScopeRoutes
machinesEach route of this page: lint, read, run, send outputs and answers, cancel.
machines:writeAlso needed to save a version, to publish a version and to delete a Machine.
jobs:readWith 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.

Check a procedure

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

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

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

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

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 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 with details.latest_version.
  • Version numbers never repeat, also after a delete.
{
"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.

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" }
}
FieldMeaning
versionSaved runs only. With no version, the run uses the published version.
procedure, toolsInline runs only. A procedure with errors gives 400 procedure_invalid and no job.
inputsThe inputs that the procedure declares. A file input is {"url": "https://…", "name": "…"} or {"id": "…"}.
options.exception_modeldefault, or off: each model rung goes to the next rung.
options.caller_timeout_sThe seconds that your system has for each tool call: 60 to 86,400. Default 600.
notify, deadline, metadataThe job fields. Read Jobs and 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.

An unknown Machine or version gives 404 not_found. Too many active runs give 429 concurrency_limited. The API creates no job for these answers. An Idempotency-Key applies to both run start routes. Read 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

{
"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"
}
]
}
typeThe run waits forSend it with
tool_callsThe output of a call of a caller tool.POST /v2/machines/runs/{id}/tool-outputs
answerThe answer of a person: {seq, code, reason, question, schema, attachments}.POST /v2/machines/runs/{id}/answers
inputsA 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:

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:

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

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.

A send for a call, a hold or an input that the run does not wait for gives 409 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.

{
"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
}
statusJob statusMeaning
newqueued or runningThe run has not started its first step.
runningrunningThe engine runs steps, for example a Paperwork tool or a model call.
waitingneeds_inputThe run waits for a tool output or an input.
held, outcome: nullneeds_inputThe run waits for the answer of a person.
held, outcome: "held"succeededThe run ended with a hold that cannot resume. Read The result.
done, refused, abortedsucceededThe procedure ended. report holds the report.
errorfailedThe engine failed. error holds the cause.
cancelledcancelledThe credential that started the run cancelled it.
expiredexpiredThe 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:

{
"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 }
}
outcomeCause
doneThe run got to the end of the steps, or a finish step with done.
refusedA finish step with refused: a business refusal.
abortedA finish step with aborted. The engine ran the compensations.
heldA 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 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.
  • Stream: send Accept: text/event-stream on the run start or on GET /v2/jobs/{id}. Read 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.

Limits

LimitValue
Active runs of an organization20 with test keys, 500 with live keys
Lifetime of a run7 days, then the job is expired
Storage of a runDeleted 30 days after the start, with the job
Body of a run start4 MiB
Inputs of a run1 MiB
One tool output1 MiB
Tool outputs in one request16
Log entries of a run20,000. Then the run fails with log_limit.
Machines of an organization500
Versions of a Machine1,000

A size limit gives 400 invalid_request with details.limit. The limits of a procedure are on the language page.

Billing

EventCreditsWhen
machine_run2A run that ends with a succeeded job: each outcome.
machine_model_calls2Each call of the exception model.
machine_decide_calls1Each 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

StatusCodeCause
400procedure_invalidThe procedure does not compile. details.diagnostics lists why.
400invalid_requestA body, an input, an output or an answer is not valid, or a limit.
402credits_exhaustedA run start or a resume with no credits.
404not_foundNo Machine or version with this name.
404job_not_foundNo run with this id, or the credential cannot use it.
409version_conflictbase_version is not the latest version.
409not_waitingThe run does not wait for this call, hold or input.
429concurrency_limitedThe organization has too many active runs.