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

# OpenAI compatible API

> **Note**
>
> 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.

| Route                       | What                                                       |
| --------------------------- | ---------------------------------------------------------- |
| `GET /v2/models`            | Lists 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/completions` | Starts 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](/paperwork/v2/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.

```ts
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}`.

```json
{
  "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](#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.

```ts
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](/paperwork/v2/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_`.

| Function         | When                                                           | Arguments                               | Send back                                                                                      |
| ---------------- | -------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `machine_person` | The 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_input`  | The 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_wait`   | The 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

```json
{
  "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 run                                | `finish_reason` | `message`                                            | `machine`                                                    |
| -------------------------------------- | --------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| Waits for a tool, a person or an input | `tool_calls`    | One tool call.                                       | `idempotency_key` of a tool call.                            |
| Ended with `done`                      | `stop`          | `content` is the report.                             | `output` is the [result](/paperwork/v2/machines#the-result). |
| Ended with `refused` or `aborted`      | `stop`          | `content` is `null`, `refusal` is the report.        | `output`                                                     |
| Ended with a hold                      | `stop`          | `content` is the reason of the hold.                 | `status: "held"`, `hold`, `output`                           |
| Failed, cancelled or expired           | `stop`          | `content` 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}`](/paperwork/v2/machines#the-run-object).

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

| Field                                                                                                                                                       | Rule                                                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                                                                                                                                                     | Required. `machine/<name>` or `machine/<name>@<version>`.                                                                                         |
| `messages`                                                                                                                                                  | Required. 1 to 500 messages.                                                                                                                      |
| `tools`                                                                                                                                                     | Optional. 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_choice`                                                                                                                                               | Absent, `auto` or `required`. Another value gives `400 unsupported_parameter`.                                                                    |
| `stream`                                                                                                                                                    | `false` or absent.                                                                                                                                |
| `n`, `response_format`, `modalities`, `logprobs`, `store`                                                                                                   | Only `1`, `{"type": "text"}`, `["text"]`, `false` and `false`.                                                                                    |
| `machine_inputs`                                                                                                                                            | An 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`, `metadata`           | Accepted 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_tier` | Refused: `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:

```json
{
  "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](/paperwork/v2/errors), or one of the codes in [OpenAI route errors](/paperwork/v2/errors#openai-route-errors).

| Status | `code`                  | Cause                                                                                                                   |
| ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 404    | `model_not_found`       | No Machine or version has this model id, or the id has a bad format.                                                    |
| 400    | `unsupported_parameter` | The request has a field that the API refuses, `stream: true` or a `tool_choice` that it does not support.               |
| 400    | `invalid_tool_call_id`  | The tool call ids of one assistant message name more than one run, or a `tool` message answers no tool call of the run. |
| 400    | `tools_mismatch`        | `tools` does not name each caller tool of the version.                                                                  |
| 400    | `inputs_required`       | A new run has no value for a required input. The message names the inputs.                                              |
| 400    | `tool_output_required`  | A `user` message came when the run waits for a tool output or a person.                                                 |
| 404    | `job_not_found`         | The tool call ids name a run that does not exist, or that another credential started.                                   |