Machines
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.
- Write a procedure with the Machine language.
- Run a Machine from an OpenAI SDK with the OpenAI compatible API.
Concepts
Scopes
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.
The answer is 200, also when the procedure has errors:
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.
runsandlintare 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 callPOST /v2/machines/{name}/versions/{version}/publish. - A procedure with errors gives
400 procedure_invalidwithdetails.diagnostics. The API saves nothing. - A save of the same procedure and tools as the latest version saves nothing. The answer is
200with that version. A new version answers201. base_versionprotects against two writers. When it is not the latest version, the answer is409 version_conflictwithdetails.latest_version.- Version numbers never repeat, also after a delete.
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.
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.
- Start the run.
- Read
required_action: in the Job of the answer, in thejob.needs_inputwebhook or stream event, or withGET /v2/machines/runs/{id}. After a resume, the fresh action is in the resume answer. - Do the action: run the tool call, get the answer of a person, or get the input.
- Send the result to the run. The answer is the run at its next stop, with its next
required_action. - 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
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:
- The output must match the
outputSchemaof the tool. A mismatch gives400 invalid_requestwithdetails.issues, and the call stays pending. - An error output has
"is_error": trueand"output": {"code", "message", "retryable"?}. Acodefrom thex-errorsof the tool matches anon_errorcase of the step. Another code goes to theelseof the step.retryable: truemarks a transient error. idempotency_keyis the same for each attempt of one step, also for a retry with changed arguments. To run each attempt, use the tool callidas your key.- After
deadline_at, the engine treats the call as a timeout. Areadstep can call again. Awritestep holds with the codeunknown_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:
A value that does not match schema gives 400 invalid_request, and the hold stays open.
Send an input
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.
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:
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.endpointon the run start. Thejob.needs_inputevent carries the Job withrequired_action. Read Webhooks. - Stream: send
Accept: text/event-streamon the run start or onGET /v2/jobs/{id}. Read Streaming. - Poll:
GET /v2/machines/runs/{id}withPrefer: wait=N. - List:
GET /v2/jobs?capability=machineslists the runs. - Log:
GET /v2/machines/runs/{id}/log?after_seq=0&limit=100reads the event log in seq order, up to 500 entries per page. Sendnext_after_seqto 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
A size limit gives 400 invalid_request with details.limit. The limits of a procedure are on the language page.
Billing
- 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
usageshows the credits when the job ends.