Skip to main content
POST
Submit Vote

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

authorization
string | null

Path Parameters

experiment_id
string<uuid>
required

Body

application/json

Request to submit a vote.

Votes are bound to the currently served sticky pair via pair_id.

pair_id
string<uuid>
required

Pair ID returned by GET next-pair (sticky)

winner_id
string<uuid> | null
required

Winning sample id for left_wins/right_wins outcomes.

axis_outcomes
AxisOutcome · object[] | null

Per-criterion outcomes for a multi-axis experiment. Mutually exclusive with the scalar outcome/winner_id (which are sugar for the single 'default' axis). The route layer enforces that all experiment axes are present; tie/cannot_tell count as answering.

client_metric_version
string | null

Client-side telemetry schema version

Maximum string length: 64
feedback
string | null

Optional feedback text explaining the choice

Maximum string length: 2000
outcome
enum<string> | null

Vote outcome. Required when winner_id is omitted. Non-choice outcomes do not count for ranking or spend.

Available options:
left_wins,
right_wins,
tie,
both_bad,
cannot_tell
sample_a_playback_percent
number | null

Playback percentage observed on sample A (audio flows)

Required range: 0 <= x <= 100
sample_a_playback_seconds
number | null

Playback seconds observed on sample A (audio flows)

Required range: x >= 0
sample_b_playback_percent
number | null

Playback percentage observed on sample B (audio flows)

Required range: 0 <= x <= 100
sample_b_playback_seconds
number | null

Playback seconds observed on sample B (audio flows)

Required range: x >= 0
sample_scores
VoteSampleScore · object[] | null

Absolute per-sample scores for numeric axes in a mixed multi-axis vote.

time_taken_ms
integer | null

Time taken to make the decision in milliseconds

Required range: x >= 0

Response

Successful Response

Response after submitting a vote.

created_at
string<date-time>
required
experiment_id
string<uuid>
required
id
string<uuid>
required
pair_id
string<uuid>
required
sample_a_id
string<uuid>
required
sample_b_id
string<uuid>
required
voter_id
string<uuid>
required
winner_id
string<uuid> | null
required
bot_probability
number | null
comparisons_spent
integer
default:0
counted_for_ranking
boolean
default:true
counted_for_spend
boolean
default:true
credit_cost
integer
default:0
effective_reliability
number | null
feedback
string | null
is_exam
boolean
default:false
new_thoughts_balance
integer | null
next_pair
NextPairResponse · object | null

Response with the next pair to compare.

next_pair_state
enum<string>
default:error
Available options:
ready,
completed,
paused,
no_comparisons,
no_pairs_available,
blocked,
error
outcome
string
default:left_wins
progress
VoteProgressResponse · object | null

Updated voting progress after a submitted vote.

remaining_comparisons
integer
default:0
selection_score
number | null
thoughts_earned
integer
default:0
time_taken_ms
integer | null
vote_cost_credits
integer
default:1