Otium Public API

Liveness probe.

Answers only "is this process running". It never consults a dependency, and that is the point: a downed database or payload key store is a readiness condition, not a reason to restart the process. Restarting cannot reach an unreachable vault — it just churns the pod and blocks the rollout that would carry the fix. Unauthenticated.

Responses

Readiness probe.

Reports the observed health of the dependencies that gate every payload path — the database and the payload encryption key store — so a load balancer can route around a degraded instance. Use /livez for liveness. Unauthenticated.

Responses

Submit a job.

Validates, persists, and acknowledges a single inference job, then returns immediately — scheduling and execution happen asynchronously. **Idempotency.** Send the `Idempotency-Key` header (or the body's `idempotency_key`, the same key; sending both with different values is a `400`) to make resubmission safe. With the header, a repeat of the same request returns the original job with the original status and `Idempotent-Replayed: true`, showing the job as it is now; the same key with a different request is a `422`. With only the body field, a repeat returns the existing job with `200`.

Parameters

Request body SubmitJobRequest

Responses

Get a job.

Returns a job by id. A tenant may only read its own jobs.

Parameters

Responses

List files.

Parameters

Responses

Upload a batch input file.

Uploads a JSONL batch input file (`purpose=batch`). Each line is a `BatchRequestInput`. OpenAI-compatible. Uploads above the server limit are rejected with `413`.

Request body

Responses

Get file metadata.

Parameters

Responses

Delete a file.

Parameters

Responses

Download file content.

Streams the raw JSONL content of a file.

Parameters

Responses

Start a multi-part upload of a large batch input file.

OpenAI's Uploads API, for a file too large for one `POST /v1/files` request (a request through the edge is capped at 100 MB). Create the upload with the file's exact size, add its bytes in parts of at most 64 MiB each (in any order, retrying a failed part alone), then complete it with the part ids in file order. The upload expires an hour after it is created; an expired or cancelled upload's parts are deleted. A whole upload may declare at most 8 GiB. A gzipped JSONL is accepted here as on `/v1/files`: it is recognized by its content.

Request body

Responses

Add a part to an upload.

Adds up to 64 MiB of the file. Parts may arrive in any order and in parallel; their order in the file is the order `complete` lists them in.

Parameters

Request body

Responses

Complete an upload into a batch input file.

Joins the listed parts, in the order listed, into a file usable as a batch's `input_file_id`. The parts must belong to this upload, appear once each and add up to the size the upload was created with. Completing an upload that already completed returns it again, with the same file. `md5` is accepted and not checked.

Parameters

Request body

Responses

Cancel an upload.

Cancels a pending upload; its parts are deleted shortly after.

Parameters

Responses

Not served (Otium is batch-only).

Otium has no synchronous chat endpoint: it runs work that can wait, on a deadline. This route exists only to say so with an OpenAI-shaped `404` carrying `code: batch_only`, so a gateway or SDK that tries its default path shows the caller a reason instead of a bare "not found". Send the same requests as a batch: upload a JSONL file to `/v1/files`, then create the batch at `/v1/batches`.

Responses

List batches.

Parameters

Responses

Create a batch.

Creates a batch over a previously uploaded input file. OpenAI-compatible. **Completion window → SLA tier.** `completion_window` accepts OpenAI's `24h` (and empty, treated as `24h`), the shorthands `1h` / `6h` / `7d` / `168h`, and Otium's own tier names as an extension — the flexible-deadline knob. **Data residency.** Set `metadata.boundary` (e.g. `us`, `eu`) to lock every job in the batch to a residency boundary. **Upgrades.** By default a job may run on a warm, larger model at its own product's price. Set `metadata.allow_upgrade` to `"false"` to keep this batch on the models it names, or `"true"` to allow it on an account that has upgrades switched off. **Idempotency.** Send an `Idempotency-Key` header and a repeat of the same request returns the original batch object byte for byte, with `Idempotent-Replayed: true`, instead of creating a second batch over the same file.

Parameters

Request body CreateBatchRequest

Responses

Get a batch.

The OpenAI batch, plus `waiting` while it is `in_progress`: its requests that have not started, by model, and why. `request_counts` moves only as requests finish, so `waiting` is what tells work that is held from work that is stuck. A request is `held` while the provisioner gathers enough work to share a GPU's boot or waits for a cheaper price (never past `latest_start`), `starting` while capacity is being started (a cold start takes 15-30 minutes, longer when a cloud has no capacity), `queued` behind a serving worker, or `billing_hold` on the account's funds or monthly spend cap. OpenAI clients ignore the field.

Parameters

Responses

Cancel a batch.

Requests cancellation: the batch moves to `cancelling`, the processor stops outstanding jobs and finalizes what completed. Idempotent while already `cancelling`. Cancelling a terminal batch is a `409`.

Parameters

Responses

List the models you can submit to.

The offered products plus the previews granted to your account (`preview: true`), OpenAI-compatible (`client.models.list()` works unchanged). Each `id` is what a request's `model` field names. `context_window` is the most tokens, prompt plus completion, one request may use; it is omitted when one number would not be true (a product that runs several models). Sorted by `id`; an empty catalog is `data: []`.

Responses

List workflows.

Your workflows, one entry per name, with the latest version and how many versions exist.

Responses

Publish a workflow version.

Validates, compiles and stores a workflow document as a new version of the workflow it names. Send the YAML as the raw body (`curl --data-binary @workflow.yaml`), or as JSON `{"document": "<yaml>"}` with `Content-Type: application/json`. Up to 1 MiB. **Idempotent.** Publishing a document identical to an existing version creates nothing: it returns that version with `200` and `created: false`, so publishing on every merge is safe. A new version is `201` with `created: true`. A document that does not compile is `422` with every finding in `diagnostics`. So is one whose `tools.endpoint` names a tool endpoint you have not registered.

Request body WorkflowDocumentEnvelope

Responses

Validate a workflow document without publishing it.

Compiles a document and returns the findings, and, when it compiles, its summary (critical path, durations, estimated cost) and a Mermaid diagram. Writes nothing. The body is the same as for publishing. Validation always answers `200`; read `ok` and `diagnostics` for the verdict.

Parameters

Request body WorkflowDocumentEnvelope

Responses

Run a workflow's unit tests.

Runs a test suite (the contents of a `*.test.yaml` file) against a workflow document, with each case's node outputs supplied by the suite instead of a model. Writes nothing and runs no inference. The same runner as `otiumctl workflow test`. A suite that runs is `200` whether or not its cases pass; the report says which. A document that does not compile, a suite that does not parse or is invalid, or a suite that does not finish within 15 seconds is `422`.

Request body WorkflowTestRequest

Responses

List a workflow's versions.

Parameters

Responses

Get a workflow version and its document.

Parameters

Responses

Deprecate a workflow version.

Stops new runs from using the version. Nothing is deleted: existing runs reference it, and it stays readable. A purged version cannot be changed (`409`).

Parameters

Responses

Get a workflow version's compiled plan.

The plan the scheduler runs from: topological order, critical path, edges, barriers, affinity and cache groups, and per-node estimates. `mermaid` and `summary` come from the document, so a purged version returns its plan without them.

Parameters

Responses

List asset bundles.

Your asset bundles: the versioned reference data a workflow's prompts render from. One entry per bundle, with its latest version.

Responses

Publish an asset bundle version.

Publishes a new version of a bundle. Each entry in `assets` is either a string (one value shared by every run) or an object of key to string (one value per key). Publishing content identical to the bundle's latest version creates nothing: it returns that version with `200` and `created: false`, so a CI job can republish on every run. A new version is `201`. A bundle is at most 8 MiB.

Request body AssetPublishRequest

Responses

List a bundle's versions.

Every version of one bundle, newest first. Metadata only, never content.

Parameters

Responses

Get a bundle version with its content.

One version's metadata and its assets. A purged version has no assets.

Parameters

Responses

Deprecate a bundle version.

Stops new runs from pinning this version. Runs that already pinned it keep it. Its content stays; to destroy the content, purge it.

Parameters

Responses

Purge a bundle version's content.

Destroys the version's content and keeps its record, so runs that used it still say which version they rendered from. Refused with `409` while a live run pins the version: wait for it to finish.

Parameters

Responses

List run sets.

Your run sets, oldest first. A batch that names a workflow becomes one run set with one run per input line; a continuation is a run set too (`continues_set_id`). Keyset-paged: pass the previous page's `next_cursor` as `after`.

Parameters

Responses

Get a run set.

A run set's aggregate state: its status, how many runs finished, a live per-status count, and the queued work being held before it starts (`holds`). **Held is not stuck.** Otium may hold queued work before booting a GPU: to gather enough work to share one boot (`gathering`), or to wait for a cheaper spot price (`price`). The set still reads `running` (the work is accepted and will run) and `holds` names the nodes held, how many runs each, and the latest start, by which capacity is started regardless. **Two clocks.** `execution_budget_seconds` is the SLA bought (it stops while a run waits on you); `expires_at` is the separate wall-clock bound. They are never collapsed into one "time remaining". **Set-scope nodes.** When the workflow has `scope: set` nodes, `set_run` names the run that carries them: `{status: "pending"}` until every item has finished, then its id, status and outcome. The counts are items only; the set is `running` until the set run has finished too.

Parameters

Responses

List a run set's runs.

One run per input item, keyset-paged like the set listing. Items only: the set run (custom_id `$set`), which carries a workflow's set-scope nodes, is not one of them and is never listed here; read it with `GET /v1/run-sets/{id}/set`.

Parameters

Responses

Get a run set's set run.

The run that carries the workflow's set-scope nodes, which run once per submission after every item has finished, exactly as `GET /v1/runs/{id}` returns it. Its `custom_id` is `$set`. While the items are still running the answer is `409` with their counts, so a client can poll this one URL for the result that reads across the whole submission.

Parameters

Responses

Download a run set's results.

JSONL, one line per run: the same lines a workflow batch writes to its output file. Any set has one, including a continuation, which an API call created and which therefore has no batch file of its own.

Parameters

Responses

Rerun a run set from a step.

Starts a new run set over this one's items, against a version of the same workflow, that reruns the steps in `from` and everything downstream of them and reuses this set's recorded output for every other step. Use it to measure a change to one step without buying the steps before it again: only the rerun steps are charged. Every reused step must be identical in both versions, its prompt, product, schemas, validators, condition and inputs included; if one changed, the answer is `409` naming it, so add it to `from`. A recorded skip is reused as made. Items whose content was deleted under the retention policy, or whose reused steps did not finish, are left out and counted in `excluded`. `dry_run: true` creates nothing and answers what the rerun would cover and cost. Like a batch line, a run your balance or spend cap cannot cover is created `hold`. Idempotent: the same source, version and steps return the set the first call created, with `200` and `existing: true`.

Parameters

Request body RerunRequest

Responses

Continue a run set.

Starts a new run set that resumes every unfinished run in this one. Nodes that already produced a valid output are carried over (`inherited_nodes`) and are not bought again; only the rest run (`rerunning_nodes`). It is a new purchase with a fresh reservation, admitted like a batch line: a run your balance or monthly spend cap cannot cover is created `hold` (`held_runs`) and starts on its own once it can. Idempotent: a repeat returns the continuation the first call created with `200` and `existing: true`. It is `409` when there is nothing to continue, when the set has not stopped yet, or when its content was deleted under the retention policy.

Parameters

Responses

List the runs waiting at an external node.

The runs in a set currently parked at one external node, with each one's rendered input, so you can do the work and resume them in bulk. The cohort is live, not a snapshot: runs arrive at a park at different times, so an empty page now does not mean the cohort is finished, and you resume in waves.

Parameters

Responses

Download one node's results across a set, in OpenAI batch-output format.

One node's results for every run in the set, each line a `BatchRequestOutput`, so code that already reads OpenAI batch output keeps working while you move a pipeline onto a workflow one stage at a time. An unknown node key is `404`, never an empty file.

Parameters

Responses

Resume parked runs in bulk.

Resumes runs parked at an external node from one JSONL body, a line per run: `{"custom_id": "...", "output": {...}}`. Each output goes through the node's validators. Safe to retry after a timeout: a line naming a run already resumed is a no-op that reports success, so re-sending the whole file is always correct. One bad line fails that line only (see `results`) and never rejects the body. Up to 32 MiB per body and 4 MiB per line.

Parameters

Request body

Responses

Get a run.

One input item's run through the graph: each node's status, output, and, while the node waits behind a held cold start, `hold`. **Three durations.** `budget_consumed_seconds` is the SLA clock, which includes the wait for capacity; `parked_seconds` is time spent waiting on you, which the SLA clock does not count; `execution_seconds` is the time workers actually spent on the run, retries included. Compare `execution_seconds` with a plan's p95 execution.

Parameters

Responses

List a node's attempts.

Every attempt at one node, oldest first: the model and region that served it, its output (rejected or accepted), the validator verdicts, tokens and cost, and when a worker leased it. Debug a validator here: a rejected output is visible only on its attempt.

Parameters

Responses

Cancel a run.

Stops one run: its unfinished nodes end `failed` with reason `cancelled`, jobs not yet leased are stopped, and the run ends `cancelled`. Cancelling a finished run changes nothing and returns it.

Parameters

Responses

Continue one run.

The single-run form of `POST /v1/run-sets/{id}/continue`, for debugging. Same idempotency and `409` rules.

Parameters

Responses

Resume one parked run.

Supplies an external node's output for one run. For more than a handful of runs use the set's bulk resume. A rejected output leaves the node parked, so you can send it again.

Parameters

Request body ResumeRequest

Responses

List webhook endpoints.

Your registered endpoints, and the events you can subscribe to. A notification carries ids, counts and a link to an authenticated listing, never a prompt or a result.

Responses

Register a webhook endpoint.

Registers an `https` URL to notify. With no `events`, it subscribes to the set-level events only (`run_set.completed`, `run_set.node_parked`); per-run events fire once per item and must be named. At most 10 endpoints per account. The response carries the signing secret. It is shown once and cannot be retrieved again; if you lose it, rotate. Each delivery is signed in the `Otium-Signature` header.

Request body WebhookEndpointRequest

Responses

List recent webhook deliveries.

Recent deliveries to all your endpoints, newest first: what was sent, how many tries, and what your endpoint answered. A delivery that used up its retries is kept as `dead`.

Parameters

Responses

Get a webhook endpoint.

One endpoint, with its last success and failure. Never the secret.

Parameters

Responses

Update a webhook endpoint.

Changes the URL, description, subscribed events or enabled flag. A field left out is unchanged.

Parameters

Request body WebhookEndpointRequest

Responses

Delete a webhook endpoint.

Removes the endpoint and its delivery history.

Parameters

Responses

Rotate a webhook endpoint's signing secret.

Issues a new signing secret, shown once in this response.

Parameters

Responses

List one endpoint's recent deliveries.

As `GET /v1/webhooks/deliveries`, for one endpoint.

Parameters

Responses

List tool endpoints.

Your registered tool endpoints: the URLs a workflow's tool nodes call, named by `tools: { endpoint }` in the workflow document.

Responses

Register a tool endpoint.

Registers an `https` URL under a name a workflow can refer to. The name is lowercase letters, digits, `-` or `_`, and cannot change later. At most 20 endpoints per account. The response carries the signing secret Otium signs each call with. It is shown once and cannot be retrieved again; if you lose it, rotate.

Request body ToolEndpointRequest

Responses

Get a tool endpoint.

One endpoint. Never the secret.

Parameters

Responses

Update a tool endpoint.

Changes the URL or description. A field left out is unchanged. The name cannot change, because published workflows refer to it; register a new endpoint instead.

Parameters

Request body ToolEndpointRequest

Responses

Delete a tool endpoint.

Removes the endpoint.

Parameters

Responses

Rotate a tool endpoint's signing secret.

Issues a new signing secret, shown once in this response. The old one stops working at once.

Parameters

Responses

Get the signed-in account.

The account the CLI token belongs to. An API key gets `403`.

Responses

List API keys.

The account's API keys, newest first, revoked ones included. A key's secret is never returned here; `last_four` identifies it. An API key gets `403`: only a person (a CLI token) manages keys.

Responses

Create an API key.

Mints an API key for programs and CI. The response carries the full `secret` once: it is never stored or shown again, so save it now. An API key gets `403`.

Request body APIKeyCreateRequest

Responses

Revoke an API key.

Revokes one of the account's keys. Revoking twice is not an error. An API key gets `403`.

Parameters

Responses

Start a CLI sign-in.

Starts the OAuth device authorization grant (RFC 8628) that `otiumctl auth login` runs. Show the person `user_code` and `verification_uri`; they approve it in the portal, signed in and re-entering their password (and second factor when MFA is on). Then poll `POST /v1/auth/device/token` every `interval` seconds until `expires_in` runs out. Unauthenticated and rate-limited per client IP.

Request body DeviceStartRequest

Responses

Poll for a CLI sign-in's token.

Until the person approves the sign-in, this answers `400` with an RFC 8628 error code: `authorization_pending` (keep polling), `slow_down` (poll less often), `access_denied`, `expired_token` (start again) or `invalid_grant` (unknown or already used). Once approved it returns the credentials, exactly once. Unauthenticated and rate-limited per client IP.

Request body DevicePollRequest

Responses

Renew a CLI sign-in.

Exchanges a refresh token for a new access token and a new refresh token (RFC 6749 §6). Each refresh token works once: presenting one that was already used revokes the sign-in. A sign-in ends after 30 days unused or 90 days in all; any failure is `401` `invalid_grant`, and the CLI signs in again. Unauthenticated and rate-limited per client IP.

Request body TokenRefreshRequest

Responses

Sign this CLI token out.

Revokes the user token the request authenticated with (`otiumctl auth logout`). Other sign-ins are managed from the portal's Devices page. An API key gets `403`.

Responses