API models
Generated section
Generated by scripts/gen_api_docs.py from schemas/openapi.json. Do not edit it by hand: change the source,
then run uv run python scripts/gen_docs.py.
Every model the dashboard API reads or returns, with its fields. The
Python source of truth is ratchet/models.py (core models) and
ratchet/dashboard_api/views.py (view models).
CapView
| Field |
Type |
Required |
Description |
purpose |
string |
yes |
— |
usd_per_day |
number |
yes |
— |
CostTile
| Field |
Type |
Required |
Description |
cache_share |
number or null |
no |
— |
cached_prompt_tokens_by_tier |
map of integer |
no |
— |
prompt_tokens_by_tier |
map of integer |
no |
— |
tokens_by_tier |
map of integer |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
CostWindow
GET /costs?from=&to=: totals for [from, to).
| Field |
Type |
Required |
Description |
cache_share |
number or null |
no |
— |
cached_prompt_tokens_by_tier |
map of integer |
no |
— |
from |
string (date-time) |
yes |
— |
prompt_tokens_by_tier |
map of integer |
no |
— |
to |
string (date-time) |
yes |
— |
tokens_by_tier |
map of integer |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
CostsView
Counterfactual
The savings line: judge spend over every verdict in the window (the last 7 days, or from/to) — the tiles' population — vs the same judge tokens priced on Ultra.
| Field |
Type |
Required |
Description |
actual_usd |
number |
yes |
— |
actual_usd_by_tier |
map of number |
no |
— |
all_ultra_usd |
number |
yes |
— |
n_verdicts |
integer |
no |
— |
saved_ratio |
number |
yes |
— |
CriteriaIn
| Field |
Type |
Required |
Description |
criteria |
array of string |
yes |
— |
CriterionCheck
| Field |
Type |
Required |
Description |
criterion |
string |
yes |
— |
evidence_steps |
array of string |
no |
— |
met |
boolean |
yes |
— |
DayCost
| Field |
Type |
Required |
Description |
day |
string |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
DemoEventIn
Demo funnel event. kind is also accepted as name (the dashboard's field). Anything not listed here is rejected, so an IP, user agent or free text cannot be smuggled in. ts is accepted and ignored: rows carry the server's time.
| Field |
Type |
Required |
Description |
device |
mobile | tablet | desktop or null |
no |
— |
kind |
demo.landing_view | demo.simulate_click | demo.verdict_view | demo.evidence_open | demo.action_click | demo.repo_click | demo.video_click |
yes |
— |
props |
map of string or integer |
no |
— |
referrer |
devpost | youtube | github | other | none or null |
no |
— |
session_hash |
string |
yes |
— |
ts |
string (date-time) or null |
no |
— |
DigestView
| Field |
Type |
Required |
Description |
blocked |
array of string |
yes |
— |
digest_id |
string |
yes |
— |
merged |
array of string |
yes |
— |
metrics |
array of MetricRow |
no |
— |
narrative |
string |
yes |
— |
period_end |
string (date-time) |
yes |
— |
period_start |
string (date-time) |
yes |
— |
simulated_models |
boolean |
no |
— |
usd |
number |
no |
— |
verdict_ids |
array of string |
yes |
— |
DriftCheck
| Field |
Type |
Required |
Description |
attributable |
boolean or null |
no |
— |
changed |
boolean |
yes |
— |
confidence |
number |
yes |
— |
fact_id |
string |
yes |
— |
new_value |
string or null |
yes |
— |
old_value |
string |
yes |
— |
query |
string |
yes |
— |
replay_value |
string or null |
no |
— |
ruling |
string |
no |
— |
source_title |
string or null |
no |
— |
source_url |
string or null |
no |
— |
statement |
string |
no |
— |
status |
checked | unavailable |
no |
— |
tavily_results_ref |
string |
yes |
— |
EditView
| Field |
Type |
Required |
Description |
diff |
string |
yes |
— |
edit |
SkillEdit |
yes |
— |
state |
string |
yes |
— |
verdict_id |
string or null |
yes |
— |
EnvSnapshot
| Field |
Type |
Required |
Description |
frozen_time |
string (date-time) |
yes |
— |
harness_version |
string |
yes |
— |
skills_commit |
string |
yes |
— |
workspace_ref |
string |
yes |
— |
world_ref |
string or null |
no |
— |
ErrorBody
| Field |
Type |
Required |
Description |
code |
string |
yes |
— |
details |
any or null |
no |
— |
message |
string |
yes |
— |
request_id |
string or null |
yes |
— |
ErrorEnvelope
| Field |
Type |
Required |
Description |
error |
ErrorBody |
yes |
— |
Event
One row of the events table, the product's spine.
| Field |
Type |
Required |
Description |
id |
integer |
yes |
— |
kind |
string |
yes |
— |
payload |
object |
yes |
— |
ref |
string |
yes |
— |
session_hash |
string or null |
no |
— |
ts |
string (date-time) |
yes |
— |
HealthView
| Field |
Type |
Required |
Description |
components |
map of string |
yes |
— |
ok |
boolean |
yes |
— |
JudgeOpinion
| Field |
Type |
Required |
Description |
causal_explanation |
string or null |
no |
— |
caused_by_diff |
boolean or null |
no |
— |
completion_tokens |
integer |
no |
— |
confidence |
number |
yes |
— |
criteria_met |
array of CriterionCheck |
no |
— |
evidence_steps |
array of string |
yes |
— |
failure_summary |
string or null |
no |
— |
possible_drift_fact |
string or null |
no |
— |
prompt_hash |
string |
no |
— |
prompt_tokens |
integer |
no |
— |
reasons |
array of string |
yes |
— |
tier |
nano | super | ultra |
yes |
— |
truncated |
boolean |
no |
— |
usd |
number |
yes |
— |
verdict |
equivalent | regressed | improved | uncertain |
yes |
— |
LLMCall
| Field |
Type |
Required |
Description |
api |
chat | responses |
no |
— |
cached_prompt_tokens |
integer |
no |
— |
completion_tokens |
integer |
yes |
— |
content_preview |
string |
no |
— |
kind |
string |
no |
— |
latency_ms |
integer |
yes |
— |
messages_ref |
string |
yes |
— |
model |
string |
yes |
— |
prompt_tokens |
integer |
yes |
— |
purpose |
agent | screen | check | adjudicate | extract | narrative | bench | embed |
no |
— |
request_hash |
string |
yes |
— |
response_ref |
string |
yes |
— |
started_at |
string (date-time) |
yes |
— |
step_id |
string |
yes |
— |
tier |
nano | super | ultra |
yes |
— |
tool_calls_requested |
array of string |
no |
— |
usage_estimated |
boolean |
no |
— |
usd |
number |
yes |
— |
LastEditCost
| Field |
Type |
Required |
Description |
cache_share |
number or null |
no |
— |
cached_prompt_tokens_by_tier |
map of integer |
no |
— |
counterfactual_usd |
number |
yes |
— |
edit_id |
string or null |
yes |
— |
prompt_tokens_by_tier |
map of integer |
no |
— |
tokens_by_tier |
map of integer |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
verdict_id |
string or null |
yes |
— |
Level0Finding
| Field |
Type |
Required |
Description |
changed_args |
array of array of any |
yes |
— |
golden_run_id |
string |
yes |
— |
hard_fail |
boolean |
yes |
— |
missing_calls |
array of ToolCall |
yes |
— |
missing_hard |
boolean |
no |
— |
new_calls |
array of ToolCall |
yes |
— |
output_similarity |
number |
no |
— |
replay_run_id |
string |
yes |
— |
LogsView
GET /edits/{id}/logs: the edit's batch worker.log tails plus crash info.
| Field |
Type |
Required |
Description |
lines |
array of string |
yes |
— |
truncated |
boolean |
no |
— |
| Field |
Type |
Required |
Description |
action_token |
string or null |
yes |
— |
bench_report_url |
string or null |
yes |
— |
harness |
string |
yes |
— |
public_mode |
boolean |
yes |
— |
repo_url |
string or null |
yes |
— |
runner |
string |
yes |
— |
sandbox |
string |
yes |
— |
simulate_enabled |
boolean |
yes |
— |
simulate_mode |
live | replayed |
yes |
— |
simulated_models |
boolean |
yes |
— |
version |
string |
yes |
— |
video_url |
string or null |
yes |
— |
MetricRow
One product-metrics row, as ratchet metrics prints it.
| Field |
Type |
Required |
Description |
metric |
string |
yes |
— |
value |
string |
yes |
— |
MetricsView
GET /metrics/product and GET /metrics/demo.
| Field |
Type |
Required |
Description |
rows |
array of MetricRow |
yes |
— |
since |
string (date-time) |
yes |
— |
Page_EditView_
| Field |
Type |
Required |
Description |
items |
array of EditView |
yes |
— |
next_cursor |
string or null |
no |
— |
Page_Event_
| Field |
Type |
Required |
Description |
items |
array of Event |
yes |
— |
next_cursor |
string or null |
no |
— |
Page_TraceSummary_
| Field |
Type |
Required |
Description |
items |
array of TraceSummary |
yes |
— |
next_cursor |
string or null |
no |
— |
Page_VerdictSummary_
| Field |
Type |
Required |
Description |
items |
array of VerdictSummary |
yes |
— |
next_cursor |
string or null |
no |
— |
PairVerdict
| Field |
Type |
Required |
Description |
control_outcome |
agrees | diverges or null |
no |
— |
control_run_id |
string or null |
no |
— |
decided_by |
level0 | nano | super | ultra | drift | infra | control |
no |
— |
drift |
array of DriftCheck |
yes |
— |
error_code |
string or null |
no |
— |
golden_run_id |
string |
yes |
— |
level0 |
Level0Finding |
yes |
— |
opinions |
array of JudgeOpinion |
yes |
— |
outcome |
pass | regression | drift | improved | uncertain | failed |
yes |
— |
reason |
string |
no |
— |
replay_run_id |
string |
yes |
— |
task_input |
string |
no |
— |
task_label |
string |
no |
— |
usd |
number |
yes |
— |
PairView
| Field |
Type |
Required |
Description |
decision |
PASS | WARN | BLOCK or null |
yes |
— |
golden |
Trace |
yes |
— |
pair |
PairVerdict |
yes |
— |
recorded |
boolean |
no |
— |
replay |
Trace |
yes |
— |
verdict_id |
string |
yes |
— |
Progress
| Field |
Type |
Required |
Description |
elapsed_s |
number |
yes |
— |
k |
integer |
yes |
— |
n |
integer |
yes |
— |
stage |
string |
yes |
— |
stage_label |
string |
yes |
— |
stages |
array of StageView |
yes |
— |
stalled |
boolean |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
PurposeCost
| Field |
Type |
Required |
Description |
calls |
integer |
yes |
— |
purpose |
string |
yes |
— |
tier |
nano | super | ultra |
yes |
— |
tokens |
integer |
yes |
— |
usd |
number |
yes |
— |
ReblessView
| Field |
Type |
Required |
Description |
archived_run_id |
string |
yes |
— |
new_golden_run_id |
string |
yes |
— |
toast |
string or null |
no |
— |
RunView
| Field |
Type |
Required |
Description |
agent_tier |
string |
yes |
— |
blessed |
boolean |
yes |
— |
last_activity_at |
string (date-time) |
yes |
— |
n_steps |
integer |
yes |
— |
run_id |
string |
yes |
— |
source |
captured | live | golden |
yes |
— |
task_label |
string |
yes |
— |
task_preview |
string |
yes |
— |
RunsView
| Field |
Type |
Required |
Description |
items |
array of RunView |
yes |
— |
ScenarioView
| Field |
Type |
Required |
Description |
catches |
string |
yes |
— |
expected_decision |
PASS | WARN | BLOCK |
yes |
— |
learned |
string |
yes |
— |
recorded_verdict_id |
string or null |
no |
— |
scenario_id |
string |
yes |
— |
skill |
string |
yes |
— |
title |
string |
yes |
— |
SettingsView
| Field |
Type |
Required |
Description |
caps |
array of CapView |
yes |
— |
harness |
string |
yes |
— |
models |
map of string |
yes |
— |
runner |
string |
yes |
— |
sandbox |
string |
yes |
— |
webhook_configured |
boolean |
yes |
— |
SimulateView
| Field |
Type |
Required |
Description |
edit_id |
string or null |
yes |
— |
eta_s |
integer or null |
no |
— |
queue_position |
integer or null |
no |
— |
scenario_id |
string |
yes |
— |
session_hash |
string |
yes |
— |
status |
running | queued | done |
yes |
— |
verdict_id |
string or null |
yes |
— |
SkillEdit
| Field |
Type |
Required |
Description |
affected_skills |
array of string |
yes |
— |
author |
agent | user | seeded |
yes |
— |
commit |
string |
yes |
— |
detected_at |
string (date-time) |
yes |
— |
diff_ref |
string |
yes |
— |
edit_id |
string |
yes |
— |
files |
array of string |
yes |
— |
parent |
string |
yes |
— |
session_hash |
string or null |
no |
— |
summary |
string |
no |
— |
StageTiming
| Field |
Type |
Required |
Description |
elapsed_ms |
integer |
yes |
— |
stage |
string |
yes |
— |
started_at |
string (date-time) |
yes |
— |
StageView
| Field |
Type |
Required |
Description |
detail |
string |
no |
— |
key |
string |
yes |
— |
label |
string |
yes |
— |
status |
pending | active | done | skipped |
yes |
— |
TickerView
| Field |
Type |
Required |
Description |
live |
boolean |
yes |
— |
total_usd |
number |
yes |
— |
usd_by_tier |
map of number |
yes |
— |
| Field |
Type |
Required |
Description |
args_hash |
string |
yes |
— |
args_norm |
object |
yes |
— |
blocked |
boolean |
no |
— |
cassette_key |
string or null |
yes |
— |
kind |
string |
no |
— |
result_hash |
string or null |
yes |
— |
result_preview |
string |
no |
— |
side_effect |
none | read | write_reversible | write_irreversible | destructive | external_send | spend |
yes |
— |
source |
cassette | live | local |
yes |
— |
started_at |
string (date-time) or null |
no |
— |
step_id |
string |
yes |
— |
tool |
string |
yes |
— |
Trace
| Field |
Type |
Required |
Description |
agent_tier |
nano | super | ultra |
yes |
— |
archived_reason |
string or null |
no |
— |
artifacts_ref |
string or null |
yes |
— |
blessed_at |
string (date-time) or null |
no |
— |
candidate_commit |
string or null |
yes |
— |
created_at |
string (date-time) |
yes |
— |
env |
EnvSnapshot |
yes |
— |
error_code |
string or null |
no |
— |
final_output |
string |
yes |
— |
golden_of |
string or null |
yes |
— |
harness_ok |
boolean |
no |
— |
kind |
live | golden | replay |
yes |
— |
run_id |
string |
yes |
— |
seed |
integer |
yes |
— |
skills_invoked |
array of string |
yes |
— |
steps |
array of any |
yes |
— |
success_criteria |
array of string |
no |
— |
task_input |
string |
yes |
— |
task_label |
string |
no |
— |
world_dependent |
boolean |
yes |
— |
world_facts |
array of WorldFact |
yes |
— |
TraceSummary
| Field |
Type |
Required |
Description |
blessed_at |
string (date-time) or null |
yes |
— |
created_at |
string (date-time) |
yes |
— |
kind |
live | golden | replay |
yes |
— |
last_replayed_at |
string (date-time) or null |
yes |
— |
n_facts |
integer |
yes |
— |
run_id |
string |
yes |
— |
skills_invoked |
array of string |
yes |
— |
task_input |
string |
yes |
— |
task_label |
string |
yes |
— |
world_dependent |
boolean |
yes |
— |
Verdict
| Field |
Type |
Required |
Description |
action |
merged | held | reverted |
yes |
— |
action_commit |
string or null |
no |
— |
affected_skills |
array of string |
no |
— |
approved_at |
string (date-time) or null |
no |
— |
author |
string |
no |
— |
batch_ids |
array of string |
no |
— |
cost |
map of number |
yes |
— |
counterfactual_usd |
number |
no |
— |
created_at |
string (date-time) |
yes |
— |
decision |
PASS | WARN | BLOCK |
yes |
— |
duration_s |
integer |
yes |
— |
edit_id |
string |
yes |
— |
headline |
string |
no |
— |
narrative |
string |
yes |
— |
pairs |
array of PairVerdict |
yes |
— |
reasons |
array of string |
no |
— |
recorded |
boolean |
no |
— |
replay_cost |
map of number |
no |
— |
rolled_back_at |
string (date-time) or null |
no |
— |
rolled_back_by |
string or null |
no |
— |
runner |
string |
no |
— |
session_hash |
string or null |
no |
— |
simulated_models |
boolean |
no |
— |
stages |
array of StageTiming |
no |
— |
tokens |
map of integer |
no |
— |
verdict_id |
string |
yes |
— |
VerdictSummary
| Field |
Type |
Required |
Description |
action |
merged | held | reverted |
yes |
— |
affected_skills |
array of string |
yes |
— |
created_at |
string (date-time) |
yes |
— |
decision |
PASS | WARN | BLOCK |
yes |
— |
edit_id |
string |
yes |
— |
headline |
string |
yes |
— |
n_pairs |
integer |
yes |
— |
outcome_counts |
map of integer |
yes |
— |
recorded |
boolean |
yes |
— |
simulated_models |
boolean |
yes |
— |
usd_total |
number |
yes |
— |
verdict_id |
string |
yes |
— |
VerdictView
| Field |
Type |
Required |
Description |
diff |
string |
yes |
— |
edit |
SkillEdit |
yes |
— |
progress |
Progress or null |
yes |
— |
state |
string |
yes |
— |
toast |
string or null |
no |
— |
verdict |
Verdict or null |
yes |
— |
verdict_id |
string |
yes |
— |
WorldFact
| Field |
Type |
Required |
Description |
fact_id |
string |
yes |
— |
query_hint |
string |
yes |
— |
source_step |
string |
yes |
— |
statement |
string |
yes |
— |
value |
string |
no |
— |
volatile |
boolean |
yes |
— |