Reference

Otium Public API

v0.1.0

The public submit surface. Point an OpenAI-compatible client at our base URL, or call the native job endpoints directly.

Download OpenAPI spec All docs

Authentication

Every endpoint except the health probes takes a bearer token: Authorization: Bearer <api-key>. Create a key in the customer portal under Developers. Keys are scoped to one account — treat them as secrets and rotate them if exposed.

Health

Liveness / readiness probes.

GET /livez No auth

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

Status	Meaning
`200`	The process is running. HealthOK

GET /healthz No auth

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

Status	Meaning
`200`	Healthy. HealthOK
`503`	A gating dependency (database or key store) is unavailable; this instance is degraded. HealthDegraded

Jobs

Otium-native job submission and lookup.

POST /v1/jobs

Submit a job.

Validates, persists, and acknowledges a single inference job, then returns immediately — scheduling and execution happen asynchronously. **Idempotency.** Supply `idempotency_key` to make resubmission safe: a repeat with the same key (per tenant) returns the original job with `200` instead of creating a second. A brand-new job is created with `201`.

Request body SubmitJobRequest

Field	Type	Description
`model` (required)	string	What to run. An intent alias (e.g. `otium-medium`) or an exact catalog model id. Required. An alias is resolved to a concrete model server-side; an unresolvable value is rejected with 400.
`otium`	OtiumIntent	Optional intent extension — declare an outcome (task, quality floor, family) rather than only a model. OpenAI-compatible (stock clients ignore it).
`tier`	Tier	SLA tier. Omit to default to `remnant`. `rushprioritystandardremnant`
`payload`	string	Small inline request body (PoC). Production payloads live in object storage.
`idempotency_key`	string	Per-tenant key making resubmission safe. A repeat returns the original job.
`max_attempts`	integer	Max execution attempts before dead-lettering. Non-positive values default to 3. Default: `3`
`boundary`	Boundary	Locks the job to a residency boundary. Empty means unconstrained. `afapaccaeueu-demenasaukus`
`sensitivity`	Sensitivity	Data-sensitivity class. Empty defaults to `internal` (trusted-only). `confidentialinternalpublic`
`max_tokens`	integer	Output-token ceiling. Bounds the up-front cost estimate the prepaid gate reserves; 0 uses a default ceiling.

Responses

Status	Meaning
`200`	Idempotent replay — the existing job for this idempotency key. Job
`201`	Job created. Job
`400`	Invalid request (bad JSON, missing model, unknown tier or boundary). NativeError
`429`	Per-client-IP submit rate limit exceeded.
`503`	Database unavailable. NativeError

GET /v1/jobs/{id}

Get a job.

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

Parameters

Parameter	In · type	Description
`id` (required)	path · string (uuid)	Job id.

Responses

Status	Meaning
`200`	The job. Job
`404`	Not found, or owned by another tenant. NativeError

Files

OpenAI-compatible Files API (batch input upload, output download).

GET /v1/files

List files.

Parameters

Parameter	In · type	Description
`purpose`	query · string	Filter by purpose. Omit for all of the tenant's files.

Responses

Status	Meaning
`200`	A single page of files (OpenAI list envelope). FileList

POST /v1/files

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

Status	Meaning
`200`	Uploaded file metadata. FileObject
`400`	Unsupported purpose or missing file field. OpenAIError
`413`	File exceeds the maximum upload size. OpenAIError

GET /v1/files/{id}

Get file metadata.

Parameters

Parameter	In · type	Description
`id` (required)	path · string	File id (e.g. `file-<uuid>`).

Responses

Status	Meaning
`200`	File metadata. FileObject
`404`	No such file (or owned by another tenant). OpenAIError

DELETE /v1/files/{id}

Delete a file.

Parameters

Parameter	In · type	Description
`id` (required)	path · string	File id (e.g. `file-<uuid>`).

Responses

Status	Meaning
`200`	Deletion acknowledgement. FileDeleted
`404`	No such file (or owned by another tenant). OpenAIError

GET /v1/files/{id}/content

Download file content.

Streams the raw JSONL content of a file.

Parameters

Parameter	In · type	Description
`id` (required)	path · string	File id (e.g. `file-<uuid>`).

Responses

Status	Meaning
`200`	Raw JSONL content.
`404`	No such file (or owned by another tenant). OpenAIError

Batches

OpenAI-compatible Batch API.

GET /v1/batches

List batches.

Parameters

Parameter	In · type	Description
`limit`	query · integer	Max batches to return. Defaults to the server's page size.

Responses

Status	Meaning
`200`	A single page of batches (OpenAI list envelope). BatchList

POST /v1/batches

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.

Request body CreateBatchRequest

Field	Type	Description
`input_file_id` (required)	string	Id of an uploaded file with purpose `batch`, owned by the caller.
`endpoint`	string	The only endpoint supported today. `/v1/chat/completions` Default: `/v1/chat/completions`
`completion_window`	string	OpenAI `24h` (default), the shorthands `1h` / `6h` / `7d` / `168h`, or an Otium tier name (`rush`, `priority`, `standard`, `remnant`). Default: `24h`
`metadata`	map of string	Up to 16 string key/value pairs. The reserved key `boundary` locks every job in the batch to a residency boundary.

Responses

Status	Meaning
`200`	The created batch (status `validating`). Batch
`400`	Invalid request (bad JSON, missing input_file_id, unsupported endpoint/window, too much metadata, invalid boundary). OpenAIError
`404`	input_file_id does not exist or is not owned by the caller. OpenAIError

GET /v1/batches/{id}

Get a batch.

Parameters

Parameter	In · type	Description
`id` (required)	path · string	Batch id (e.g. `batch_<uuid>`).

Responses

Status	Meaning
`200`	The batch. Batch
`404`	No such batch (or owned by another tenant). OpenAIError

POST /v1/batches/{id}/cancel

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

Parameter	In · type	Description
`id` (required)	path · string	Batch id (e.g. `batch_<uuid>`).

Responses

Status	Meaning
`200`	The batch, now `cancelling` (or unchanged if already cancelling). Batch
`404`	No such batch (or owned by another tenant). OpenAIError
`409`	The batch is in a terminal status and cannot be cancelled. OpenAIError

Schemas

The object shapes the endpoints above accept and return.

Tier

SLA tier — the completion window the caller will wait.

rushprioritystandardremnant

Boundary

Data-residency boundary (never a raw cloud region). Empty means unconstrained. Coarse and fine tags coexist (e.g. a region in `eu` may also be in `eu-de`).

afapaccaeueu-demenasaukus

Sensitivity

Data-sensitivity class. Empty defaults to `internal` (trusted-only). Sets the minimum worker trust tier the job may run on. See docs/trust-tiers.md.

confidentialinternalpublic

TrustTier

Minimum worker trust tier required to run the job, derived from its sensitivity at submit. Control-plane-assigned to workers; never self-reported.

known_providerowner_trusteduntrusted

JobStatus

Position in the job lifecycle state machine.

acceptedholdqueuedscheduleddispatchedrunningsucceededfailedinterruptedexpireddead_lettercancelled

BatchStatus

OpenAI batch lifecycle status.

validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled

SubmitJobRequest

Field	Type	Description
`model` (required)	string	What to run. An intent alias (e.g. `otium-medium`) or an exact catalog model id. Required. An alias is resolved to a concrete model server-side; an unresolvable value is rejected with 400.
`otium`	OtiumIntent	Optional intent extension — declare an outcome (task, quality floor, family) rather than only a model. OpenAI-compatible (stock clients ignore it).
`tier`	Tier	SLA tier. Omit to default to `remnant`. `rushprioritystandardremnant`
`payload`	string	Small inline request body (PoC). Production payloads live in object storage.
`idempotency_key`	string	Per-tenant key making resubmission safe. A repeat returns the original job.
`max_attempts`	integer	Max execution attempts before dead-lettering. Non-positive values default to 3. Default: `3`
`boundary`	Boundary	Locks the job to a residency boundary. Empty means unconstrained. `afapaccaeueu-demenasaukus`
`sensitivity`	Sensitivity	Data-sensitivity class. Empty defaults to `internal` (trusted-only). `confidentialinternalpublic`
`max_tokens`	integer	Output-token ceiling. Bounds the up-front cost estimate the prepaid gate reserves; 0 uses a default ceiling.

OtiumIntent

The optional `otium` selection extension: declare an outcome instead of a model. Rung 1 routes on the `model` alias alone; these fields are carried for the measured router and planner (later rungs) and do not yet change the resolved model.

Field	Type	Description
`task`	string	The task kind, e.g. extract \| classify \| summarize \| generate \| chat.
`quality`	string	The quality floor — the cheapest execution that meets it, e.g. good \| high \| best.
`family`	string	Model-family constraint — auto (default) \| qwen \| gemma \| glm \| an exact model id.

Job

The durable record of one unit of deferred inference work.

Field	Type	Description
`id` (required)	string (uuid)
`idempotency_key`	string
`tenant` (required)	string
`product`	string	The sellable SKU the job was submitted under (billing keys on it). Empty for pre-product jobs.
`model` (required)	string	The concrete model the job runs on (dispatch/provisioning key on it).
`status` (required)	JobStatus	`acceptedholdqueuedscheduleddispatchedrunningsucceededfailedinterruptedexpireddead_lettercancelled`
`tier` (required)	Tier	`rushprioritystandardremnant`
`deadline` (required)	string (date-time)	SLA deadline; the job expires if not completed by this time.
`boundary`	Boundary	`afapaccaeueu-demenasaukus`
`sensitivity`	Sensitivity	`confidentialinternalpublic`
`required_trust`	TrustTier	`known_providerowner_trusteduntrusted`
`run_id`	string	Workflow run this job is an attempt of. Empty for an ordinary job. A workflow job is scheduled, leased and executed by exactly the same path as any other; these two fields are only how a completion finds its graph node.
`node_key`	string	Workflow node this job is an attempt of. Empty for an ordinary job.
`attempts` (required)	integer
`max_attempts` (required)	integer
`last_error`	string	Category/summary of the last failure. Never contains payload content.
`payload`	string
`result`	string
`input_ref`	string	Object-storage key for the input when not stored inline.
`result_ref`	string	Object-storage key for the result when not stored inline.
`leased_by`	string	Worker id holding the job while running.
`lease_expires_at`	string (date-time)
`created_at` (required)	string (date-time)
`updated_at`	string (date-time)
`queued_at`	string (date-time)
`scheduled_at`	string (date-time)
`started_at`	string (date-time)
`finished_at`	string (date-time)
`input_tokens`	integer
`output_tokens`	integer
`cached_tokens`	integer
`cost_usd`	number
`estimated_cost_usd`	number

FileObject

OpenAI representation of an uploaded or generated file.

Field	Type	Description
`id` (required)	string
`object` (required)	string	`file`
`bytes` (required)	integer (int64)
`created_at` (required)	integer (int64)	Creation time, Unix seconds.
`filename` (required)	string
`purpose` (required)	string	`batchbatch_output`

FileList

Field	Type	Description
`object` (required)	string	`list`
`data` (required)	array of FileObject
`has_more`	boolean

FileDeleted

Field	Type	Description
`id` (required)	string
`object` (required)	string	`file`
`deleted` (required)	boolean

CreateBatchRequest

Field	Type	Description
`input_file_id` (required)	string	Id of an uploaded file with purpose `batch`, owned by the caller.
`endpoint`	string	The only endpoint supported today. `/v1/chat/completions` Default: `/v1/chat/completions`
`completion_window`	string	OpenAI `24h` (default), the shorthands `1h` / `6h` / `7d` / `168h`, or an Otium tier name (`rush`, `priority`, `standard`, `remnant`). Default: `24h`
`metadata`	map of string	Up to 16 string key/value pairs. The reserved key `boundary` locks every job in the batch to a residency boundary.

Batch

OpenAI representation of a batch. Unset timestamps serialize as null.

Field	Type	Description
`id` (required)	string
`object` (required)	string	`batch`
`endpoint` (required)	string
`errors`	BatchErrorList
`input_file_id` (required)	string
`completion_window` (required)	string
`status` (required)	BatchStatus	`validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled`
`output_file_id`	string
`error_file_id`	string
`created_at` (required)	integer (int64)	Unix seconds.
`in_progress_at`	integer (int64), nullable
`expires_at`	integer (int64), nullable
`finalizing_at`	integer (int64), nullable
`completed_at`	integer (int64), nullable
`failed_at`	integer (int64), nullable
`expired_at`	integer (int64), nullable
`cancelling_at`	integer (int64), nullable
`cancelled_at`	integer (int64), nullable
`request_counts` (required)	RequestCounts
`metadata`	map of string

BatchList

Field	Type	Description
`object` (required)	string	`list`
`data` (required)	array of Batch
`has_more`	boolean

RequestCounts

Per-batch progress tally.

Field	Type	Description
`total` (required)	integer
`completed` (required)	integer
`failed` (required)	integer

BatchErrorList

Non-fatal errors discovered during validation.

Field	Type	Description
`object` (required)	string	`list`
`data` (required)	array of BatchError

HealthOK

Field	Type	Description
`status` (required)	string	`ok`

HealthDegraded

Field	Type	Description
`status` (required)	string	`degraded`
`database` (required)	string	`down`

NativeError

Native-surface error envelope (`POST /v1/jobs`, `GET /v1/jobs/{id}`).

Field	Type	Description
`error` (required)	string

OpenAIError

OpenAI-compatible error envelope used by the Files and Batch endpoints.

Field	Type	Description
`error` (required)	object

Send your first batch.

Otium is in closed alpha. Leave your email and we’ll send an invite with an API key when a spot opens.

No credit card, no spam — one email when your invite is ready.

Closed alpha — onboarding is gated while we calibrate. Already invited? Sign in.