Training API

Access and availability

Use https://api.reliqua.ai with Authorization: Bearer followed by your workspace key. training:read permits the GET routes below; training:write permits reads and the listed mutations. These scopes do not permit editing saved resources: prepare the draft with a separate resources:write key or the workspace.

Read capabilities before preparing a run. A valid key, a saved draft or an uploaded file does not establish execution availability. Launch also requires active training approval, operator-enabled execution, a matching approved profile, an available qualified executor and a supported billing mode.

This is the owned customer training API. Public Teutonic run monitoring and miner accounting are separate read APIs. Saving a catalog RL draft does not make private RL execution available.

Authentication — Choose a scope and keep browser sessions separate from API keys.

Training workflow — Prepare a compatible profile, dataset and saved configuration.

API overview — Base URLs, shared response rules and contract coverage.

Routes and scopes

All paths below begin with /api/v1/training. The prefix alone is not a list endpoint; use /tasks for owned runs. IDs in these paths are returned by the API.

Check capabilities

Capabilities are an observation, not a reservation. A profile or executor can change between this read, a quote and the explicit launch request.

Read capabilities without creating a run

: "${TRAINING_API_KEY:?Set a training:read or training:write key}"
curl --fail-with-body --silent --show-error --max-time 15 \
  -H "Authorization: Bearer $TRAINING_API_KEY" \
  'https://api.reliqua.ai/api/v1/training/capabilities'

Upload a dataset

POST raw UTF-8 JSONL bytes, not multipart data or a JSON object wrapping the file. The current upload limit is 5 MiB; text formats accept 1–10,000 examples and vision accepts 1–256. A successful upload establishes supported file format and storage, not training quality or gains.

instruction requires prompt and response; preference requires prompt, chosen and rejected; corpus requires text. The vision format has its own reviewed row/media rules and must match a vision-capable profile. Choose the format expected by the approved profile.

The response is {file:{id,name,sha256,size,rows,format,created_at,archived_at}}. A new file returns 201; reuse of identical stored bytes returns 200. Retain the returned ID and digest.

Uploads are content-addressed per owner. Retrying the exact same bytes can repair an interrupted storage write; Idempotency-Key is not the upload mechanism. Existing metadata is reused, so a repeated upload is not a rename or format-change operation.

GET /files returns at most 200 records with no cursor; archived=true selects archived records. Active-file limits are 5 for preview accounts and 100 otherwise; retained library limits are 10 and 200 respectively. Archiving does not remove the retained record. A dataset supporting a run or active quote returns dataset_in_use instead of being archived.

Upload a synthetic instruction file

: "${TRAINING_API_KEY:?Set a training:write key}"
printf '%s\n' '{"prompt":"What is two plus two?","response":"Four."}' > training-example.jsonl
curl --fail-with-body --silent --show-error --max-time 20 \
  -H "Authorization: Bearer $TRAINING_API_KEY" \
  -H 'Content-Type: application/x-ndjson' \
  -H 'X-Filename: training-example.jsonl' \
  -H 'X-Dataset-Format: instruction' \
  -H 'X-Data-Authorized: true' \
  --data-binary @training-example.jsonl \
  'https://api.reliqua.ai/api/v1/training/files'

Dataset preparation — Supported data formats and the library workflow.

Import a delivered generation file

kind is catalogue or pinned, matching the actual generation order. Use the returned order/delivery/file identities; the synthetic values above only illustrate the schema. A successful import returns the same file envelope as an upload.

Import request body

{
  "kind": "catalogue",
  "orderId": "order-example",
  "deliveryId": "dl-order-example",
  "fileName": "samples.jsonl",
  "name": "training-data.jsonl",
  "format": "instruction",
  "rightsConfirmed": true
}

Review a service-credit quote

POST /quotes with application/json and {draftId,revision,datasetId}. revision is the saved resource's positive numeric revision. The selected dataset, exact draft revision and approved live profile must still match. Quotes are supported in service-credits mode; an operator-funded pilot does not use this quote corridor.

The response is {quote:{id,draftId,revision,datasetId,profileDigest,rateMicroUsdPerHour,maxSeconds,maxCostMicroUsd,expiresAt,policy}}. expiresAt is Unix seconds; quotes last 10 minutes. policy is successful-allocation-only. Monetary fields are integer micro-USD, where 1 USD equals 1,000,000 micro-USD.

Creating a quote does not launch a run or reserve credits. Read the rate, maximum allocation, cost ceiling and expiry before deciding whether to confirm. A changed draft, dataset, profile or rate requires a new reviewed quote.

Request a quote for existing reviewed inputs; no launch

: "${TRAINING_API_KEY:?Set a training:write key}" "${DRAFT_ID:?Set an owned training draft ID}" "${DATASET_ID:?Set an owned file ID}" "${DRAFT_REVISION:?Set the numeric draft revision}"
jq -n --arg draftId "$DRAFT_ID" --arg datasetId "$DATASET_ID" \
  --argjson revision "$DRAFT_REVISION" \
  '{draftId:$draftId,revision:$revision,datasetId:$datasetId}' > training-quote-request.json
curl --fail-with-body --silent --show-error --max-time 20 \
  -H "Authorization: Bearer $TRAINING_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @training-quote-request.json \
  'https://api.reliqua.ai/api/v1/training/quotes'

Explicit launch confirmation

POST /tasks is the separate action that starts the run workflow and, in service-credits mode, reserves the reviewed maximum cost. The upload and quote examples above deliberately stop before this request.

Send application/json, a retained Idempotency-Key of 16–80 letters, digits, underscores or hyphens, and the body below. quoteId is required in service-credits mode and omitted for an operator-funded pilot. This route uses revision in the body; it does not use the saved-resource mutation header as a substitute.

Reuse the same key and identical reviewed inputs if the response is uncertain. A key used for another draft, revision, dataset or quote returns idempotency_conflict. Re-read current capabilities and inputs after an explicit refusal instead of blindly creating another run.

Confirmation body, only after reviewing the actual inputs and quote

{
  "draftId": "draft-example",
  "revision": 3,
  "datasetId": "dataset-example",
  "approveExecution": true,
  "quoteId": "quote-example"
}

Observe, download and cancel

Lists return {tasks:[...]}; task timestamps such as createdAt, allocatedAt, finishedAt and updatedAt use Unix seconds and may be null where the stage has not occurred. The task includes resourceId/resourceRevision, datasetId, status/statusReason, sequence and billingMode.

GET /tasks/:id returns {task,configuration,result,events,artifacts,billing}. It includes at most 100 recent events and 100 artifacts; there is no event cursor on this route. result and billing can be null. Returned events and artifact metadata retain their own field names.

The current pilot permits at most three non-terminal tasks and at most 100 retained task records per account. These limits do not establish available executor capacity.

Poll reads with a bounded interval and backoff, preserving the task ID. queued or starting does not mean training has completed; needs_attention requires reconciliation. Terminal states are succeeded, failed and cancelled.

POST /tasks/:id/cancel returns {requested:true}. A queued run can become cancelled immediately; starting/running work enters cancelling. The acknowledgement is not proof that runtime cleanup or financial settlement has completed.

Dataset and artifact GET routes return private binary content, not JSON. Downloads support Range: bytes=... and may return 206 with Content-Range. They do not return public presigned links.

Service-credit billing distinguishes held and settled amounts, with reservedMicroUsd, chargedMicroUsd, releasedMicroUsd and billableSeconds. Run completion, a model artifact, held-out results and settled charges are separate observations. GET /api/v1/balance reads the same account's service-credit ledger.

Errors and safe retries

Shared errors and retries — Interpret error.code and preserve uncertain request identities.

Saved resources API — Read or update the draft and its numeric revision.