Skip to navigation
Machines

OpenAI compatible API

Beta
Run a saved Machine with an OpenAI SDK. Your code runs the tool calls.
View as Markdown

Machines are in beta. The OpenAI compatible routes can change before general availability.

Each saved Machine is also a model of an OpenAI compatible API. A chat completion with the model machine/<name> runs the Machine. A tool call of the Machine comes back as an OpenAI tool_call, and your code sends the result as a tool message. Use these routes when you want only the runtime, and you run the tools in your own code.

The routes are not in the CloudRaker SDK. Use an OpenAI SDK.

RouteWhat
GET /v2/modelsLists each Machine that has a published version.
GET /v2/models/{model}Reads one model. It can name any version, a draft too.
POST /v2/chat/completionsStarts a run, or continues the run that the history names.

Each route needs the scope machines. A run of this API is a run of Machines, with the same billing and limits.

Set up the client

Set the base URL of the SDK to the API of your organization, and use an API key as the OpenAI key.

import OpenAI from 'openai'
const client = new OpenAI({
apiKey: process.env.CRK_API_KEY,
baseURL: `https://${process.env.CRK_SLUG}.cloudraker.run/v2`,
})

Models

A model id is machine/<name> (the published version) or machine/<name>@<version>. An unknown id gives 404 model_not_found. The id can be raw or URL-encoded in the path of GET /v2/models/{model}.

{
"object": "list",
"data": [
{
"id": "machine/invoice-intake",
"object": "model",
"created": 1762783331,
"owned_by": "acme",
"machine": {
"version": 1,
"caller_tools": ["erp_find_vendor", "erp_post_invoice"],
"inputs": { "tax_id": { "type": "string" }, "invoice_number": { "type": "string" }, "total": { "type": "number" } },
"pseudo_tools": [{ "type": "function", "function": { "name": "machine_person", "description": "…", "parameters": {} } }]
}
}
]
}

machine.caller_tools lists the tools that your code runs. machine.pseudo_tools holds the schemas of the pseudo tools.

Run a Machine

The client sends the full history on each request. The history carries the state of the run in the tool call ids, so the API needs no session.

import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions'
const tools: Record<string, (args: any) => Promise<unknown>> = {
erp_find_vendor: async () => ({ vendor_id: 'V-19', name: 'Acme Supply' }),
erp_post_invoice: async () => ({ document_id: 'DOC-88' }),
}
const messages: ChatCompletionMessageParam[] = [{ role: 'user', content: 'Post invoice INV-1001.' }]
for (;;) {
const completion = await client.chat.completions.create({
model: 'machine/invoice-intake',
messages,
// The inputs of the Machine. The API reads them only on the first request.
machine_inputs: { tax_id: 'CA-123', invoice_number: 'INV-1001', total: 1250 },
} as any)
const choice = completion.choices[0]!
if (choice.finish_reason !== 'tool_calls') {
console.log(choice.message.content ?? choice.message.refusal)
break
}
messages.push(choice.message)
for (const call of choice.message.tool_calls ?? []) {
if (call.type !== 'function') continue
const run = tools[call.function.name]
if (run === undefined) {
// machine_person, machine_input or machine_wait: read the section "Pseudo tools".
throw new Error(`Handle ${call.function.name}.`)
}
const output = await run(JSON.parse(call.function.arguments))
messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(output) })
}
}

The inputs of a new run

A request with no tool call id of a run starts a new run. The API gets the inputs in this order:

  1. machine_inputs, when the request has it.
  2. Else the first user message, when its text is a JSON object whose keys are all inputs of the Machine.
  3. Else the text of the last user message is the input user_message, when the Machine declares it.

The file parts (file_id or file_data) and the image_url parts (https or data:) of the user messages become the file inputs f1, f2 and so on, in order. On this route only, a file can be base64 data. The API ignores system and developer messages. A required input that is missing gives 400 inputs_required with the names.

Send a tool result

For each tool call of your tools, send a tool message with the same tool_call_id:

  • JSON content is the output. Other content is a string output.
  • {"error": {"code": "vendor_not_found", "message": "…"}} is an error output. A code from the x-errors of the tool matches an on_error case of the step.
  • An output that does not match the output schema of the tool gives a 400 error, and the call stays pending.

A resend of the same history is safe. The run ignores a result that it already took, and the answer shows the current state of the run.

Idempotency

Only an Idempotency-Key header makes a new run idempotent. With no key, two equal first requests start two runs, as in OpenAI. The continuation requests are idempotent by the tool call ids. Read Idempotency.

Pseudo tools

A run can stop for something other than a tool of your code. The API then sends a tool call of a reserved pseudo tool. A Machine cannot have a tool with the prefix machine_.

FunctionWhenArgumentsSend back
machine_personThe run waits for the answer of a person.{seq, code, reason, question, schema}A tool message with the answer. Use JSON when schema is not a string schema.
machine_inputThe run waits for a later input, for example a second message.{name, schema}A tool message with the value. For a string input, a trailing user message also works.
machine_waitThe run did not stop in 300 seconds.{retry_after_s: 5}Any tool message after retry_after_s seconds. The API ignores its content and waits again.

A trailing user message with no tool message is the input of a machine_input call. When the run waits for a tool output or a person, it gives 400 tool_output_required with the pending id.

The answer

{
"id": "chatcmpl-01JC3X5Q8ZKX4T9V0R2H7N6M3B-4",
"object": "chat.completion",
"created": 1762783331,
"model": "machine/invoice-intake",
"system_fingerprint": "bm-ir/1:6af76865c1d0",
"choices": [
{
"index": 0,
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"content": null,
"refusal": null,
"tool_calls": [
{
"id": "mc_01JC3X5Q8ZKX4T9V0R2H7N6M3B_2",
"type": "function",
"function": { "name": "erp_find_vendor", "arguments": "{\"tax_id\":\"CA-123\"}" }
}
]
}
}
],
"usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 },
"machine": {
"run_id": "job_01JC3X5Q8ZKX4T9V0R2H7N6M3B",
"version": 1,
"status": "waiting",
"credits": 0,
"idempotency_key": "job_01JC3X5Q8ZKX4T9V0R2H7N6M3B:0:"
}
}
The runfinish_reasonmessagemachine
Waits for a tool, a person or an inputtool_callsOne tool call.idempotency_key of a tool call.
Ended with donestopcontent is the report.output is the result.
Ended with refused or abortedstopcontent is null, refusal is the report.output
Ended with a holdstopcontent is the reason of the hold.status: "held", hold, output
Failed, cancelled or expiredstopcontent is null, refusal is the error message.status and error
  • A failed run answers HTTP 200 with a refusal, not an error. The request was valid.
  • id is the same for the same state of the run. system_fingerprint is bm-ir/1: and the first 12 hex digits of the hash of the compiled program.
  • usage counts the tokens of the exception model since the previous answer. Add usage over your calls to get the total of the run.
  • machine.credits is 0 until the run ends.
  • The x-machine-run header holds the run id. Read the run with GET /v2/machines/runs/{id}.

Waits

The API waits for the next stop of the run, at most 300 seconds. It does not read Prefer. When the run does not stop in that time, the answer is a machine_wait tool call.

stream: true is not available. It gives 400 unsupported_parameter.

Request fields

FieldRule
modelRequired. machine/<name> or machine/<name>@<version>.
messagesRequired. 1 to 500 messages.
toolsOptional. When the request has it, it must name each caller tool of the version, else 400 tools_mismatch. The API does not compare the schemas.
tool_choiceAbsent, auto or required. Another value gives 400 unsupported_parameter.
streamfalse or absent.
n, response_format, modalities, logprobs, storeOnly 1, {"type": "text"}, ["text"], false and false.
machine_inputsAn object: the inputs of the Machine. A file input is {"url"}, {"id"} or {"file_data", "name"?}.
machine_options{exception_model?, caller_timeout_s?}: default or off, and 60 to 86,400 seconds.
parallel_tool_calls, temperature, top_p, max_tokens, max_completion_tokens, presence_penalty, frequency_penalty, user, metadataAccepted and ignored. The x-machine-ignored header names them.
top_logprobs, functions, function_call, audio, prediction, web_search_options, seed, stop, logit_bias, reasoning_effort, service_tierRefused: 400 unsupported_parameter, and param names the field.

The API reads no notify, deadline or metadata of this body.

Errors

The OpenAI compatible routes answer errors in the OpenAI shape, with the x-request-id header:

{
"error": {
"message": "The tools of the request do not include the caller tools of the Machine: erp_post_invoice.",
"type": "invalid_request_error",
"param": "tools",
"code": "tools_mismatch"
}
}

type comes from the status: 400 and 409 give invalid_request_error, 401 authentication_error, 402 insufficient_quota, 403 permission_error, 404 not_found_error, 429 rate_limit_error and 5xx api_error.

code is a code of API v2, or one of the codes in OpenAI route errors.

StatuscodeCause
404model_not_foundNo Machine or version has this model id, or the id has a bad format.
400unsupported_parameterThe request has a field that the API refuses, stream: true or a tool_choice that it does not support.
400invalid_tool_call_idThe tool call ids of one assistant message name more than one run, or a tool message answers no tool call of the run.
400tools_mismatchtools does not name each caller tool of the version.
400inputs_requiredA new run has no value for a required input. The message names the inputs.
400tool_output_requiredA user message came when the run waits for a tool output or a person.
404job_not_foundThe tool call ids name a run that does not exist, or that another credential started.