Docs
API reference
What endpoints does the Onrup API expose?
A REST API over HTTPS with server-sent events for progress. Bearer authentication, cursor pagination, idempotency keys on mutations, and a stable namespaced error envelope. The full endpoint list is below and is also published as an OpenAPI document.
Conventions
- Versioned in the path. Breaking changes ship as a new version rather than mutating this one.
- Bearer authentication for both sessions and API keys.
- Idempotency-Key on mutating calls, honoured for 24 hours.
- Cursor pagination — responses carry items and next_cursor, with a page cap.
- Server-sent events for progress, resumable via Last-Event-ID.
- No GraphQL, no customer-configured outbound webhooks, no long-polling.
Account
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /v1/me | The authenticated identity, tenant and role. | any |
| PATCH | /v1/me | Update profile fields on the authenticated user. | session |
API keys
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/keys | Create an API key with an explicit scope set.The secret is returned once and never again. | keys:write |
| GET | /v1/keys | List keys with their scopes and last use. | keys:read |
| DELETE | /v1/keys/{id} | Revoke a key immediately. | keys:write |
Datasets
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/data-assets/uploads | Begin a resumable multipart upload.Returns presigned part URLs; bytes go straight to storage and never traverse the API. | datasets:write |
| POST | /v1/data-assets/uploads/{id}/parts | Request further presigned part URLs. | datasets:write |
| POST | /v1/data-assets/uploads/{id}/complete | Finalise an upload and trigger validation. | datasets:write |
| GET | /v1/data-assets/uploads/{id} | Upload state and which parts have landed. | datasets:read |
| DELETE | /v1/data-assets/uploads/{id} | Abandon an upload and release its parts. | datasets:write |
| GET | /v1/data-assets | List data assets with kind and state. | datasets:read |
| GET | /v1/data-assets/{id} | A single data asset and its manifest. | datasets:read |
| GET | /v1/data-assets/{id}/report | The validation report: record counts, token length percentiles, duplicates, truncation risk. | datasets:read |
| POST | /v1/data-assets/{id}/generate | Expand a seed asset into a full one under a declared cost ceiling. | datasets:write |
| DELETE | /v1/data-assets/{id} | Delete a data asset and its derived artefacts. | datasets:write |
Catalogue
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /v1/models | Base models with memory thresholds and supported objectives. | any |
| GET | /v1/templates/training | Training templates, filterable by model.Add ?include=experimental to see templates outside the stable set. | any |
| GET | /v1/templates/inference | Inference templates and their scaling options. | any |
Runs
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/runs | Create a run in draft, against a template and a data asset. | runs:write |
| POST | /v1/runs/{id}/submit | Authorise cost and queue the run.This is where spend is reserved. A run that would breach the limit is rejected here, before compute is leased. | runs:write |
| POST | /v1/runs/{id}/cancel | Cancel a run and release its reservation. | runs:write |
| POST | /v1/runs/{id}/resume | Resume an interrupted run from its last checkpoint. | runs:write |
| GET | /v1/runs | List runs with state and accrued cost. | runs:read |
| GET | /v1/runs/{id} | A single run: state, template, GPU class, cost so far. | runs:read |
| GET | /v1/runs/{id}/logs | Training logs for a run. | runs:read |
| GET | /v1/runs/{id}/metrics | Loss, throughput and validation metrics over time. | runs:read |
| GET | /v1/runs/{id}/weights | A signed URL to download the trained weights.The adapter, or the merged model where the template produced one. | runs:read |
| GET | /v1/runs/{id}/stream | Server-sent event stream of run progress. | runs:read |
Operations
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /v1/operations/{id} | State of any long-running operation. | any |
| GET | /v1/operations/{id}/events | Replay the event log from a cursor.Pass ?after=<event-id> to continue from where a client left off. | any |
| GET | /v1/operations/{id}/stream | Live event stream, resumable via Last-Event-ID. | any |
| POST | /v1/operations/{id}/cancel | Cancel an operation. | any |
| POST | /v1/operations/{id}/retry-from-checkpoint | Restart from the last durable checkpoint. | any |
Evaluation
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/evaluations | Run a blinded comparison of a candidate against a baseline.Declares a cost ceiling; the job stops at the ceiling rather than exceeding it. | runs:write |
| GET | /v1/evaluations/{id} | Evaluation state and summary. | runs:read |
| GET | /v1/evaluations/{id}/gate | The gate verdict: pass, fail or inconclusive, with win rate and interval. | runs:read |
| GET | /v1/evaluations/{id}/results | Per-case results, including which side won and why. | runs:read |
Publishing
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/runs/{id}/publications | Publish a finished run to a model hub.Weights and a generated model card only. Datasets are never included. | runs:write |
| GET | /v1/runs/{id}/publications | Publications for a run. | runs:read |
| GET | /v1/publications/{id} | State of a single publication. | runs:read |
| POST | /v1/publications/{id}/cancel | Cancel an in-flight publication. | runs:write |
| GET | /v1/runs/{id}/model-card | The generated model card, as markdown or JSON. | runs:read |
Deployments
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /v1/deployments | Create an endpoint for a finished run.min_replicas 0 for scale-to-zero, 1 or more for always warm. | deployments:write |
| POST | /v1/deployments/{id}/warm | Bring a cold endpoint up before traffic arrives. | deployments:write |
| POST | /v1/deployments/{id}/retire | Retire an endpoint and release its capacity. | deployments:write |
| POST | /v1/deployments/{id}/resume | Return a retired endpoint to service. | deployments:write |
| GET | /v1/deployments | List endpoints with state and hourly rate. | deployments:read |
| GET | /v1/deployments/{id} | A single endpoint, its URL and scaling configuration. | deployments:read |
| GET | /v1/deployments/{id}/stream | Server-sent events for warm-up and scaling transitions. | deployments:read |
Billing
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /v1/forecast/cost | Estimate a run’s cost before creating it.Takes model, template and dataset size; returns an estimate and a wait-window indication. | any |
| GET | /v1/billing/entitlement | Plan, spend limit, reserved and settled amounts, available headroom. | billing:read |
| GET | /v1/billing/usage | Usage for the current period, including events not yet settled. | billing:read |
| GET | /v1/billing/invoices | Invoice history. | billing:read |
| POST | /v1/billing/portal-session | A short-lived link to the billing portal. | session |
Inference
| Method | Path | Purpose | Scope |
|---|---|---|---|
| POST | /{tenant}/{deployment}/v1/chat/completions | OpenAI-compatible chat completions. Served from serve.onrup.com.Supports streaming, tool calling and structured output. | deployments:read |
Start with the free tier
A magic link creates your account, your tenant and your first API key. No card until you ask for compute.