API overview
A practical map of the public read APIs, scoped order APIs, and session-only workspace routes.
Base URL and response format
https://api.reliqua.ai and https://app.reliqua.ai serve the same /api routes; server and CLI integrations can use either, and browser clients keep the app’s same-origin session transport. The OpenAI-compatible Batch API is at https://app.reliqua.ai/api/openai/v1. API paths begin with /api. JSON responses use Content-Type: application/json; private downloads return the file content.
Use standard HTTP clients. These examples use curl or native fetch; no Reliquary SDK is required. Preserve each route’s field names and timestamp units rather than applying one naming convention to every response.
API base
https://api.reliqua.ai/apiChoose the right API surface
| Workflow | Reference | Authentication |
|---|---|---|
| Discover models, environments and offers | Inventory & catalogs | Public GET |
| Follow training, benchmarks and miner hotkeys | Run monitoring & RL miners | Public GET |
| Save a configuration | Resources | resources:read / resources:write or browser session |
| Validate JSONL on owned CPU workers | Jobs & CPU workers | resources scopes plus product approval |
| Generate a dataset | Dataset orders | orders:write plus dataset approval |
| Run completions on your own JSONL file (OpenAI-compatible) | Batch API | orders:write |
| Evaluate a model on your own file with references | Evaluations on your file | orders:write |
| Evaluate a model on catalog sets | Evaluations | evaluations:write |
| Upload a dataset and launch private training | Training | training:read / training:write plus training approval |
| Read service credits | Balance below | orders, evaluations or training key scope |
Batch API — OpenAI-compatible batches on your own JSONL file.
Run monitoring & RL miners — Anonymous run selection, miner hotkeys, fields, clocks and payout limits.
Resources — Saved configurations, paging and optimistic revisions.
Jobs & CPU workers — Immutable inputs, worker enrollment, attempts and reports.
Training — Capabilities, private JSONL, quotes, launch and artifacts.
Contracts, clients and machine-readable docs
The HTTP reference is authoritative for the documented platform surfaces. OpenAPI coverage is narrower: the application pins @reliquary/api 0.12.0 and publishes its generation (wire version 0.3.0), jobs (wire version 0.2.0), evaluation (wire version 0.2.0) and OpenAI-compatible Batch (wire version 0.1.0) contracts unchanged. Package versions and wire schema versions are different things.
The installed package includes generation, jobs, and evaluation clients with bounded key transports and runtime response validation, plus a bounded read-only client for public inventory, compute and network discovery. The staged Affine batch and checkpoint diagnostic clients additionally use owner-scoped training routes; the Affine pilot OpenAPI covers those shared training reads and diagnostic stages. Public run monitoring and individual RL miners also retain their HTTP reference. The package is a controlled release artifact, not a public npm installation.
Every article is also exported as Markdown under /docs-content/<article-slug>.md. /docs.json contains the structured catalog; /llms.txt is its navigation index and /llms-full.txt contains the full text. These exports are generated from the same content as this reference. OpenAPI downloads document contracts and never enable execution.
Generation OpenAPI — Installed public/key and browser generation contract.
Jobs OpenAPI — Installed jobs contract with the managed HTTPS browser-session cookie.
Evaluations OpenAPI — Installed evaluation requests, reconciliation and frozen protocol contract.
OpenAI-compatible Batch OpenAPI — Files and batches under /api/openai/v1, for the official OpenAI SDKs.
Structured documentation index — All articles and sections as JSON.
Full documentation for text clients — The same reference in one generated text file.
GET /api/v1/balance
Read the authenticated account’s shared service-credit balance with an orders:write, evaluations:write, training:read or training:write key. A resources-only key does not grant balance access. USD amounts and integer micro-USD are customer service credits, not TAO/alpha holdings, miner ledger rewards or an on-chain payment record.
Quotes estimate or cap a request; confirmation can reserve credits. Use the returned billing status and settlement receipts to distinguish reserved, charged, released and refunded amounts. The existence of credit does not bypass product approval, dispatch or qualified-runtime gates.
Request and response conventions
Send Content-Type: application/json for JSON mutations. Ordinary JSON bodies default to a 32 KiB limit; explicit exceptions include the 256 KiB job-input envelope (32 KiB content), raw 5 MiB training-library JSONL, Batch API files (32 MiB in one multipart request, 200 MiB in parts) and 24 KiB telemetry heartbeats. Follow the individual route rather than assuming one upload limit.
Private account JSON and owned downloads are no-store. Public monitoring supports ETag revalidation and bodyless 304 responses. Inspect HTTP status before parsing an error or binary file as a successful JSON payload. Preserve request and source timestamps; fields named similarly can use different units across API families.
No global pagination, rate limit or idempotency format is promised. Resources use nextCursor, jobs/events use next_cursor, and order/evaluation/training lists return bounded recent history. Creation and control keys, revision values and quote expiries are documented separately for each family.
Generation contract and typed client
The generation OpenAPI export describes the existing public catalogue, scoped dataset-order API and browser Batch corridor. It includes request and response schemas, permissions, idempotency and private download paths. It does not enable ordering, qualify a runtime or grant product access.
The application uses the versioned @reliquary/api TypeScript client and shared runtime parsers. The reviewed package is distributed as a pinned release artifact; it is not currently a public registry installation. Standard HTTP clients remain supported.
A client receives your existing request function, which must return parsed JSON on success and reject HTTP failures. Use the key audience for an orders:write server or CLI transport, or the browser audience with the existing session/XSRF transport. The client preserves confirmation keys and validates responses; it does not sign wallets, retry launches automatically or provide worker capacity.
Client with an existing authenticated transport
import { createGenerationClient } from '@reliquary/api';
// request is your existing transport to https://api.reliqua.ai.
// It handles orders:write authentication and HTTP errors.
const generation = createGenerationClient(request, { audience: 'key' });
const catalogue = await generation.catalog();
// Quote review and explicit confirmation remain separate steps.
// create(quoteId, requestKey) reuses the original key on an explicit retry.Generation OpenAPI contract — Download the customer generation contract used by this application build.
Jobs, attempts and validation reports
CPU validation, owner-scoped workers, controls and pagination have a dedicated reference. The installed Jobs OpenAPI export describes this surface, independently of paid generation or GPU training.
Jobs API — Routes, scopes, immutable inputs, revision-bound controls and reports.
Run a CPU validation with HTTP
CPU validation quickstart — Upload, submit, poll and verify one report.
Public reads
| GET route | Purpose |
|---|---|
| /api/inventory | Published task, environment, model, and dataset discovery. |
| /api/catalog | Reference workspace examples, approved profile definitions, and training templates. |
| /api/v1/generation/catalog | Qualified generation models, sources, environments, and ordering flags. |
| /api/v1/evaluations/catalog | Qualified evaluation sets and limits. |
| /api/v1/compute/offers | Filtered, ranked fresh GPU packages and provider handoffs; no account required. |
| /api/compute/catalog | Normalized provider GPU offers and checkout-mode flags. |
| /api/network | Compact network activity with independent source states. |
| /api/pay | Corpus pay estimate per active job, with its source state. |
| /api/monitoring/analytics/:view | Public analytical views with validated filters. |
| /api/monitoring/snapshot | Public widget snapshot for dashboards. |
| /api/monitoring/runs | Published current and archived training runs. |
| /api/monitoring/run | Selected trainer, benchmarks and paired observations. |
| /api/monitoring/rl/snapshot | Selected miner-fleet analytics. |
| /api/monitoring/rl/miners | Published roster and optional individual hotkey record. |
| /api/pricing/reference-rates | Source-labelled reference rates; not an execution quote. |
Authenticated surfaces
The /api/v1 integration routes require API keys. The browser corridors use session cookies and mutation XSRF checks. Credentials and permissions are not interchangeable between these surfaces.
| Surface | Use it for |
|---|---|
| /api/resources | Owned saved resources through a session or resources-scoped key. |
| /api/v1/dataset-orders | Dataset quotes and orders with orders:write. |
| /api/v1/evaluations | Evaluation quotes and orders with evaluations:write. |
| /api/v1/training | Owned training capabilities, files, quotes and runs with training:read or training:write. |
| /api/v1/balance | Shared service-credit balance for dataset, evaluation and training scopes. |
| /api/openai/v1, /api/v1/files | The Batch API: files and batches with orders:write. |
| /api/batch | The browser corridor behind the Training Data page (catalog dataset orders); not the Batch API. |
| /api/datasets/files, /api/training/quotes, /api/tasks | The native private dataset and training browser workflows. |
| /api/account/*, /api/balance | Browser account management and billing. |
Saved resource routes
Saved resources are configurations owned by the authenticated account. The supported kinds are instance, training, evaluation, dataset, storage, and cluster_quote. The server validates each kind’s config and current permission before saving.
| Method and path | Contract |
|---|---|
| GET /api/resources | Returns resources and nextCursor; optional kind, cursor, and archived=true filters. |
| GET /api/resources/:id | Returns the owned resource, including its numeric revision. |
| POST /api/resources | Send kind, name and config; an optional retained Idempotency-Key makes retries reconcilable. |
| PATCH /api/resources/:id | Send the updated configuration and current X-Resource-Revision. |
| DELETE /api/resources/:id | Archive an eligible owned resource with X-Resource-Revision. |
Make mutations deliberate
- Request and review a quote before confirming an order.
- Use Idempotency-Key on supported creation requests and keep the same key for an ambiguous retry.
- Use X-Resource-Revision when updating or archiving a saved resource.
- Re-read an owned resource after a conflict before preparing a new mutation.
- Record the HTTP status, error code, and X-Request-ID for troubleshooting.
Authentication — Choose a session or scoped API key.
Errors & retries — Handle conflicts and failed requests correctly.