JSON primitives

All Whitney v1 requests use application/json. Training data is expressed as token ID arrays and dense tensors; you do not need generated protocol code or a provider SDK.

Forward and backward

Submit this payload as the payload of a forward or forward_backward operation:

{
  "data": [
    {
      "input": { "token_ids": [9707, 374, 264] },
      "loss_inputs": {
        "target_tokens": {
          "dtype": "int64",
          "shape": [3],
          "values": [374, 264, 1273]
        },
        "weights": {
          "dtype": "float32",
          "shape": [3],
          "values": [1, 1, 1]
        }
      }
    }
  ],
  "loss_function": "cross_entropy",
  "loss_config": {}
}

Tensor values are dense and row-major. Their count must equal the product of shape. Cross-entropy targets must be int64; optional weights must be float32; both tensors must match the input length.

GRPO’s `importance_sampling` payload

RL loops align four tensors instead of two — shifted target_tokens, prompt-masked weights, the rollout-policy logprobs returned by sample(), and per-token advantages — all the same length as input.token_ids. Positions inside the prompt carry zero weight, zero logprob, and zero advantage; only completion positions carry real values:

{
  "data": [
    {
      "input": { "token_ids": [9707, 374, 264, 15592] },
      "loss_inputs": {
        "target_tokens": {
          "dtype": "int64",
          "shape": [4],
          "values": [374, 264, 15592, 1614]
        },
        "weights": {
          "dtype": "float32",
          "shape": [4],
          "values": [0, 0, 1, 1]
        },
        "logprobs": {
          "dtype": "float32",
          "shape": [4],
          "values": [0, 0, -0.31, -0.08]
        },
        "advantages": {
          "dtype": "float32",
          "shape": [4],
          "values": [0, 0, 1.22, 1.22]
        }
      }
    }
  ],
  "loss_function": "importance_sampling",
  "loss_config": {}
}

Here the model saw a 3-token prompt and a 2-token completion; input and target_tokens both cover the shifted 4-token window (the completion’s last token only ever appears as a target). The first two positions are prompt-masked to zero; the last two carry the sampler’s own logprobs and a single scalar advantage broadcast across the completion. Building this by hand for every algorithm variant is exactly what rl_datum() does — see GRPO for the full loop.

Sample

{
  "prompt": { "token_ids": [9707, 374, 264] },
  "parameters": {
    "max_tokens": 64,
    "temperature": 0.7,
    "top_p": 0.95,
    "top_k": -1,
    "min_p": 0,
    "seed": 0,
    "stop_token_ids": []
  },
  "num_samples": 4,
  "include_prompt_logprobs": false,
  "topk_prompt_logprobs": 0,
  "required_weight_version": 1
}

Use the same payload for run-scoped or explicit sampler-scoped sample. required_weight_version prevents reading stale weights.

Full operation envelope

Every primitive is posted to /v1/training/runs/{run_id}/operations or, for an existing sampler, /v1/training/samplers/{sampler_id}/operations:

{
  "seq_id": 1,
  "idempotency_key": "stable-key-for-this-operation",
  "request_hash": "sha256-of-the-canonical-envelope-without-request_hash",
  "kind": "forward_backward",
  "payload": {}
}

The request hash is SHA-256 of canonical JSON containing surface and payload:

import hashlib
import json

def canonical_json(value: object) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")

request_hash = hashlib.sha256(canonical_json({"surface": surface, "payload": body})).hexdigest()

On an ambiguous response, retry the exact same sequence ID, idempotency key, hash, and body.

Never place token or tensor payloads in URLs, logs, documentation feedback, or durable operation metadata.

Get started

How it works

Cookbooks

Distillation

Coding agents

JSON primitives

Forward and backward

GRPO’s `importance_sampling` payload

Sample

Full operation envelope

​Forward and backward

​GRPO’s importance_sampling payload

​Sample

​Full operation envelope

Forward and backward

GRPO’s `importance_sampling` payload

Sample

Full operation envelope