ValcairnRequest access

API reference

Check training files, start and follow training runs, compare models and fetch signed records in one workspace. Sign in with a workspace API key from the API keys page (linked from Team, or from Compute in a personal workspace). Every route reuses the web app's own checks: a key can do only what the person who created it can do, in that one workspace. Read-only keys never start or change anything. Starting work always takes two calls: a plan with a confirmation code, then the same request with that code.

Five-minute example: check a training file

Create an API key on your workspace's API keys page (Team for an organization, Compute for a personal workspace). Then send a JSONL file and read each problem with its line number. Checking stores nothing and starts nothing.

export VALCAIRN_KEY=vck_…          # Team or Compute page > API keys > Create key (read-only is enough)
export WS=<workspace id>          # shown on the API keys page

curl -s https://your-valcairn-site/v1/workspaces/$WS/training-files/check \
  -H "Authorization: Bearer $VALCAIRN_KEY" \
  -H 'content-type: application/json' \
  --data "$(jq -Rs '{jsonl: .}' train.jsonl)"

The answer:

{
  "ok": false, "trainable": true, "lines": 120, "usable": 118, "distinct": 117,
  "problems": [
    { "line": 14, "message": "Line 14 is not valid JSON." },
    { "line": 57, "message": "Line 57 does not end with an assistant answer." }
  ]
}

trainable is true when there are enough distinct usable examples to train on even though some lines would be skipped; ok is true only when no line has a problem.

Starting work takes two calls

A read-only key can never start anything. With a full key, the first call to start a run starts nothing: it answers 428 with the plan (model, method, dataset versions, machines, time estimate and credit cost) and a confirmation code that expires in 10 minutes. Show the plan to the person you act for. If they agree, send the identical request again with "confirmation": "<code>". The code works only for that key, workspace and request body.

Routes

Send the key on every request as Authorization: Bearer vck_…. A key works only in its own workspace and can do only what the person who created it can do there. Each key has its own per-minute request limit, and every request is recorded in the workspace audit trail with the key's name.

GET List projects

/v1/workspaces/{workspaceId}/projects

The workspace's projects, as the Projects page lists them.

Key: read-only or full.

Answers: 200, 401, 404, 429

POST Check a training file

/v1/workspaces/{workspaceId}/training-files/check

Checks JSONL training text the way the training engine reads it and returns each problem with its line number. Nothing is stored or started. Up to 1 MiB per request; the command-line tool checks larger files on your machine.

Key: read-only or full.

FieldTypeNotes
jsonlstring

Answers: 200, 400, 401, 404, 429

POST Plan a training run

/v1/workspaces/{workspaceId}/training-runs/plan

Who could run it now and why others cannot, the dataset versions, the memory need, a time estimate and the credit cost. Starts nothing.

Key: read-only or full.

FieldTypeNotes
projectId (optional)string
methodsft | lora | dpo | grpo | distill | pretrain
baseModelobject
datasetIdsarrayProject ids whose latest frozen dataset version is used, or projectId@version for one version.
computeScopethis_device | my_devices | workspace | public_pool
deviceId (optional)stringRequired when computeScope is this_device.
hyper (optional)objectOptional bounded settings: steps, localSteps, rounds, batch, seqLen, seed, lr.

Answers: 200, 400, 401, 404, 429

GET List training runs

/v1/workspaces/{workspaceId}/training-runs

The newest 100 runs in the workspace.

Key: read-only or full.

Answers: 200, 401, 404, 429

POST Start a training run

/v1/workspaces/{workspaceId}/training-runs

Two calls. The first, without confirmation, starts nothing: it answers 428 with the plan and a confirmation code that expires in 10 minutes. Show the plan to the person you act for; if they agree, send the identical request again with confirmation set to that code. The code works only for this key, this workspace and this exact body. Members start runs on their own devices; workspace and public-pool devices need an owner or admin. A public-pool run reserves the credits shown in plan.cost.

Key: full.

FieldTypeNotes
projectId (optional)string
methodsft | lora | dpo | grpo | distill | pretrain
baseModelobject
datasetIdsarrayProject ids whose latest frozen dataset version is used, or projectId@version for one version.
computeScopethis_device | my_devices | workspace | public_pool
deviceId (optional)stringRequired when computeScope is this_device.
hyper (optional)objectOptional bounded settings: steps, localSteps, rounds, batch, seqLen, seed, lr.
idempotencyKeystringThe same key returns the same run instead of starting a second one.
confirmation (optional)stringThe code from the 428 answer to this same request. Leave it out on the first call.

Answers: 200, 400, 401, 403, 404, 409, 428, 429

GET Read a training run

/v1/workspaces/{workspaceId}/training-runs/{runId}

State, progress, devices, events and, when it failed, the recorded reason in run.failure.

Key: read-only or full.

Answers: 200, 401, 404, 429

POST Create a pairing code

/v1/workspaces/{workspaceId}/device-pairings

A 6-character code, valid for 10 minutes, to link a machine running the Valcairn agent (valcairn-agentd pair CODE).

Key: full.

FieldTypeNotes
kindapp
name (optional)string

Answers: 201, 400, 401, 403, 404, 429

GET Read a pairing

/v1/workspaces/{workspaceId}/device-pairings/{pairingId}

waiting, claimed (the agent entered the code), confirmed or expired.

Key: read-only or full.

Answers: 200, 401, 404, 429

POST Confirm a pairing

/v1/workspaces/{workspaceId}/device-pairings/{pairingId}/confirm

Names the claimed machine and makes it active. Only the person who created the code (the key's creator) can confirm it.

Key: full.

FieldTypeNotes
namestring
deviceTypelaptop | desktop | workstation | phone | tablet | browser

Answers: 200, 400, 401, 403, 404, 409, 429

GET Read an evaluation set

/v1/workspaces/{workspaceId}/projects/{projectId}/evaluations/{setId}

Its cases, frozen versions with their imported answer batches, comparisons and approved reports. Use it to find the ids a comparison needs.

Key: read-only or full.

Answers: 200, 401, 404, 429

POST Compare two models

/v1/workspaces/{workspaceId}/projects/{projectId}/evaluations/{setId}/comparisons

Compares the recorded answers of a baseline batch and a candidate batch on the same frozen version. It runs no model and spends nothing; read the result with Read a comparison.

Key: full.

FieldTypeNotes
versionIdstring
baselineBatchIdstring
candidateBatchIdstring

Answers: 200, 400, 401, 403, 404, 409, 429

GET Read a comparison

/v1/workspaces/{workspaceId}/projects/{projectId}/evaluations/comparisons/{comparisonId}

summary.improvements lists cases the candidate now passes (wins), summary.regressions cases it no longer passes (losses); every other eligible case is a tie. summary.decision says whether the acceptance rule passed, and why not.

Key: read-only or full.

Answers: 200, 401, 404, 429

GET Fetch a signed record

/v1/workspaces/{workspaceId}/projects/{projectId}/evaluations/{setId}/versions/{versionId}/runs/{runId}/release/export

The release export for one approved candidate run: the evidence chain, its content hash and, when the server has a release key, an Ed25519 signature. Check it offline with `npx valcairn verify <file>`.

Key: read-only or full.

Answers: 200, 401, 404, 409, 429

Errors

Every error is JSON with a sentence in error that you can show a person, and often a code.

  • A field is missing or out of range; errors names each one.
  • No key, an unknown or revoked key (api_key_invalid), or its creator left the workspace (api_key_owner_inactive).
  • A read-only key on a route that changes something (api_key_read_only), or the creator's role does not allow it.
  • Not found, including any workspace other than the key's own.
  • Not possible in the current state, or a workspace limit was reached; error says which.
  • Nothing was started. Show plan to the person, then repeat the request with confirmation.code.
  • More than 60 requests in a minute from this key (api_key_rate_limited). Retry-After says when to retry.

Quickstart · Contact