API reference

Everything in the reward model app is available over REST under /api/v1/rm.

Authentication

Send a Stash API key as a bearer token. Create one on the API Keys page. Every endpoint reads and writes only the caller's own traces, annotations, models, and runs. If you run your own Stash, set STASH_URL to your backend instead.

export STASH_URL=https://api.joinstash.ai
export STASH_API_KEY="<your key>"

curl -s "$STASH_URL/api/v1/rm/formats" -H "Authorization: Bearer $STASH_API_KEY"

Examples on this page use those two variables. Request and response bodies are JSON unless noted.

Reward-model APIs require an account enrolled in the experiment. Accounts that existed at rollout remain disabled and receive 404 from every endpoint here. New accounts are enabled by default; eligibility is per account, including new accounts in existing organizations.

Errors

Errors return {"detail": "…"}. An id that belongs to another user is a 404, the same as one that doesn't exist. A request Stash can't act on, such as an unparseable import, a rating on a system step, or a rejected SQL query, is a 422 whose detail says why.

Formats

[{"name": "stash", "description": "…"}, {"name": "openai_chat", "description": "…"}, …]

Traces

jq -Rs '{format: "auto", data: .}' traces.jsonl \
  | curl -s "$STASH_URL/api/v1/rm/traces/import" \
      -H "Authorization: Bearer $STASH_API_KEY" \
      -H "Content-Type: application/json" \
      --data @-

{"format": "openai_chat", "imported": 128, "trace_ids": ["…", …]}

format in the response is the format that was used, which tells you what auto detected. The import is all or nothing: any error is a 422 and stores no traces. That includes auto matching no format, a payload that doesn't parse as its format, a trace with only system steps, and a trace with no title and no user step. Re-importing a trace with the same id replaces its steps and deletes the annotations on them. See Trace format.

curl -s "$STASH_URL/api/v1/rm/traces?limit=50&offset=0" -H "Authorization: Bearer $STASH_API_KEY"

Returns {"traces": [TraceSummary], "total": int}, newest first.

curl -s "$STASH_URL/api/v1/rm/traces/<trace_id>" -H "Authorization: Bearer $STASH_API_KEY"

Returns a TraceDetail. Step ids for annotating come from this response.

Send {} for the current shared evaluator, or{"reward_model_id": "<model_id>"} for a personal or previously released shared model. Returns 202 with a scoring job (id, trace_id, reward_model_id, status, error and timestamps). Poll trace detail's scoring_runs for its status and action_scores for results. Repeated requests reuse an active job. Unowned traces or unreleased models owned by others return 404; models without action training, unfinished models and traces without assistant actions return 422. This invokes the trained checkpoint, without LLM labeling or retraining.

Returns {"default": {"id": "…", "name": "…", "revision": 1, "updated_at": "…"}}. Shared weights and pooled training data are not exposed.

Send {"allowed": true} to opt in, or false to revoke future contribution. Scoring does not require contribution permission. Revocation does not unlearn released models.

curl -s -X DELETE "$STASH_URL/api/v1/rm/traces/<trace_id>" -H "Authorization: Bearer $STASH_API_KEY"

Annotations

curl -s "$STASH_URL/api/v1/rm/traces/<trace_id>/annotations" \
  -H "Authorization: Bearer $STASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id": "<step_id>", "rating": -1, "comment": "Skipped the policy check"}'

Returns the Annotation. Breaking any rule in the table is a 422.

Only the fields you send change. The step and quote are fixed once created.

curl -s -X PATCH "$STASH_URL/api/v1/rm/annotations/<annotation_id>" \
  -H "Authorization: Bearer $STASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label_error": true, "label_error_note": "Refund was within policy"}'

curl -s -X DELETE "$STASH_URL/api/v1/rm/annotations/<annotation_id>" -H "Authorization: Bearer $STASH_API_KEY"

Export

All three return JSONL (application/x-ndjson), one object per line, for everything you own.

curl -s "$STASH_URL/api/v1/rm/export/traces"      -H "Authorization: Bearer $STASH_API_KEY" > traces.jsonl
curl -s "$STASH_URL/api/v1/rm/export/annotations" -H "Authorization: Bearer $STASH_API_KEY" > annotations.jsonl
curl -s "$STASH_URL/api/v1/rm/export/pairs"       -H "Authorization: Bearer $STASH_API_KEY" > pairs.jsonl

The pairs export contains pairs built from explicit API ratings. It does not run feedback extraction or export a model's saved feedback-derived training evidence.

Reward models

curl -s "$STASH_URL/api/v1/rm/reward-models" \
  -H "Authorization: Bearer $STASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "refund-policy", "trace_ids": ["<trace_id>"]}'

Returns a RewardModel with status queued. Feedback extraction and the minimum of two usable pairs are checked in the worker. The deployment sets RM_COMPUTE; sending compute or any unknown request field returns 422. An unowned trace ID returns 404.

curl -s "$STASH_URL/api/v1/rm/reward-models/<id>" -H "Authorization: Bearer $STASH_API_KEY"

Returns {"url": "https://…"} after checking ownership and succeeded status; otherwise 404. The URL expires after five minutes. Download from that URL without forwarding your Stash API key. The gzip archive contains a reward-model/ directory with model weights, tokenizer files, reward_stats.json, and action_reward_stats.json when trained on action comparisons.

set -euo pipefail
reward_weights_url="$(curl -fsS "$STASH_URL/api/v1/rm/reward-models/<id>/weights" -H "Authorization: Bearer $STASH_API_KEY" | jq -er '.url')"
curl -fL "$reward_weights_url" --output reward-model.tar.gz
tar xzf reward-model.tar.gz

GEPA runs

curl -s "$STASH_URL/api/v1/rm/gepa-runs" \
  -H "Authorization: Bearer $STASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reward_model_id": "<reward_model_id>",
    "task_model": "openai/Qwen/Qwen3-8B",
    "task_api_base": "http://gpu-box.internal:8000/v1",
    "reflection_model": "anthropic/claude-sonnet-5"
  }'

Returns a GepaRun with status queued. Only reward_model_id is required. The worker generates the skill name and description; they are null until success.

curl -s "$STASH_URL/api/v1/rm/gepa-runs/<id>/skill" -H "Authorization: Bearer $STASH_API_KEY" -o SKILL.md

A 404 until the run has succeeded.

SQL query

Each request gets a fresh in-memory DuckDB holding only your rows. Send exactly one SELECT (or WITH … SELECT), checked with DuckDB's own parser. File and network access are disabled. Results are capped at 1000 rows, and truncated is true when there were more. A query that runs longer than 10 seconds is stopped with a 422, query exceeded 10s; DuckDB errors come back as a 422 with DuckDB's message.

curl -s "$STASH_URL/api/v1/rm/query" \
  -H "Authorization: Bearer $STASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT source_format, count(*) AS n FROM traces GROUP BY 1"}'

{"columns": ["source_format", "n"],
 "rows": [["openai_chat", 128], ["otel", 40]],
 "truncated": false}

Tables

SELECT * FROM steps LIMIT 0 returns a table's column names without any rows.

Example: negative rate per tool

Which tools are your reviewers rating down most often?

SELECT s.tool_name,
       count(*)                                        AS rated_steps,
       avg(CASE WHEN a.rating = -1 THEN 1 ELSE 0 END)  AS negative_rate
FROM annotations a
JOIN steps s ON s.id = a.step_id
WHERE a.rating IS NOT NULL
  AND NOT a.label_error
  AND s.tool_name IS NOT NULL
GROUP BY s.tool_name
ORDER BY negative_rate DESC

Example: worst-scored traces nobody has reviewed

SELECT t.title, sc.score
FROM scores sc
JOIN traces t ON t.id = sc.trace_id
WHERE sc.reward_model_name = 'refund-policy'
  AND t.id NOT IN (SELECT trace_id FROM annotations)
ORDER BY sc.score ASC
LIMIT 20

Example: where reviewers disagree

SELECT trace_id, step_index,
       count(*) FILTER (WHERE rating = 1)  AS plus,
       count(*) FILTER (WHERE rating = -1) AS minus
FROM annotations
WHERE NOT label_error
GROUP BY trace_id, step_index
HAVING plus > 0 AND minus > 0

Objects

TraceSummary

TraceDetail

Every TraceSummary field, plus:

Step

Annotation

RewardModel

GepaRun