> ## Documentation Index > Fetch the complete documentation index at: https://docs.heybee.app/llms.txt > Use this file to discover all available pages before exploring further. # Submit Anonymous Scores > Submit per-clip absolute numeric scores for the current served pair. NEW additive scoring branch that lives on the SAME anonymous token surface as /votes. It NEVER touches the pairwise selection/Thompson/BT/Elo path — it only writes raw rows into sample_scores and then reuses the next-pair SERVING to advance the shared voting UI. Scores never count toward spend or ranking. ## OpenAPI ````yaml /openapi.json post /v1/v/{token}/scores openapi: 3.1.0 info: description: Customer-owned evaluation lifecycle API. title: HeyBee Public API version: 1.0.0 servers: - description: Production url: https://api.heybee.app security: [] paths: /v1/v/{token}/scores: post: tags: - Voting Sessions summary: Submit Anonymous Scores description: >- Submit per-clip absolute numeric scores for the current served pair. NEW additive scoring branch that lives on the SAME anonymous token surface as /votes. It NEVER touches the pairwise selection/Thompson/BT/Elo path — it only writes raw rows into sample_scores and then reuses the next-pair SERVING to advance the shared voting UI. Scores never count toward spend or ranking. operationId: submit_anonymous_scores_v1_v__token__scores_post parameters: - in: path name: token required: true schema: title: Token type: string - in: query name: include_next_pair required: false schema: default: true title: Include Next Pair type: boolean - in: header name: X-Voter-Token required: false schema: anyOf: - type: string - type: 'null' title: X-Voter-Token - in: header name: authorization required: false schema: anyOf: - type: string - type: 'null' title: Authorization - in: header name: X-API-Key required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ScoreSubmitResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - {} - BearerAuth: [] - ApiKeyAuth: [] components: schemas: ScoreCreate: additionalProperties: false description: Request to submit per-clip numeric scores for the current served pair. properties: pair_id: description: Served pair id (sticky); scored samples must belong to it. format: uuid title: Pair Id type: string sample_a_playback_percent: anyOf: - maximum: 100 minimum: 0 type: number - type: 'null' description: >- Percent of clip A actually played. Required (both sides, enforced server-side) for audio experiments with enforce_playback + min_playback_percent, mirroring the vote path's engagement gate. title: Sample A Playback Percent sample_b_playback_percent: anyOf: - maximum: 100 minimum: 0 type: number - type: 'null' description: Percent of clip B actually played. See sample_a_playback_percent. title: Sample B Playback Percent scores: description: One entry per (sample, scored axis). items: $ref: '#/components/schemas/ScoreItem' minItems: 1 title: Scores type: array time_taken_ms: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Milliseconds the scorer spent on the pair. Required (and enforced server-side) when the session sets min_viewing_seconds > 0 for non-audio media, mirroring the vote path's engagement gate. title: Time Taken Ms required: - pair_id - scores title: ScoreCreate type: object ScoreSubmitResponse: description: >- Response after submitting numeric scores: raw ids + the next served pair. properties: next_pair: anyOf: - $ref: '#/components/schemas/NextPairResponse' - type: 'null' next_pair_state: default: error enum: - ready - completed - paused - no_comparisons - no_pairs_available - blocked - error title: Next Pair State type: string progress: anyOf: - $ref: '#/components/schemas/SessionProgressResponse' - type: 'null' score_ids: items: format: uuid type: string title: Score Ids type: array title: ScoreSubmitResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ScoreItem: additionalProperties: false description: One per-clip absolute numeric score for a scored axis. properties: axis_key: description: Scored axis key (must carry a scale). maxLength: 64 minLength: 1 title: Axis Key type: string notes: anyOf: - maxLength: 2000 type: string - type: 'null' description: Optional free-text note. title: Notes sample_id: description: Sample (clip) being scored; must be in the served pair. format: uuid title: Sample Id type: string score: description: Raw absolute score within the axis scale [min,max]. title: Score type: number required: - sample_id - axis_key - score title: ScoreItem type: object NextPairResponse: description: Response with the next pair to compare. properties: allow_playback_speed: default: false description: Whether audio voters may adjust playback speed title: Allow Playback Speed type: boolean anchor: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured anchor context for display title: Anchor anchor_value: anyOf: - type: string - type: 'null' description: The anchor value both samples share (if anchored experiment) title: Anchor Value axes: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: >- Voting axes [{axis_key,label,description}] for a multi-axis experiment; None/empty => single default A/B. title: Axes eligibility_policy_version: anyOf: - type: string - type: 'null' description: Eligibility policy version used to validate this pair title: Eligibility Policy Version enforce_playback: default: false description: Whether both-output playback thresholds are enforced for audio votes title: Enforce Playback type: boolean is_exam: default: false description: True if this pair is an exam pair (quality control) title: Is Exam type: boolean login_required: default: false description: >- True when the current participant is linked to an account and must log in. title: Login Required type: boolean min_playback_percent: default: 0 description: Required playback percentage for each audio output maximum: 100 minimum: 0 title: Min Playback Percent type: integer min_viewing_seconds: default: 0 description: Minimum viewing time (seconds) before voting is accepted minimum: 0 title: Min Viewing Seconds type: integer pair_id: description: Current sticky pair ID (required for vote binding) format: uuid title: Pair Id type: string participant_label: anyOf: - type: string - type: 'null' description: Short non-sensitive anonymous participant label. title: Participant Label participant_mode: anyOf: - enum: - anonymous - transferred - authenticated - linked_requires_login type: string - type: 'null' description: Current public voting participant mode. title: Participant Mode participant_required: default: false description: >- True when an anonymous voter must choose start-new or continue before a pair can be served. title: Participant Required type: boolean prefetch: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: Optional hydrated upcoming pairs for client-side media warming title: Prefetch remaining_comparisons: default: 0 description: Remaining comparisons in the experiment pool minimum: 0 title: Remaining Comparisons type: integer require_feedback: default: true description: Whether vote feedback is required for this experiment title: Require Feedback type: boolean sample_a: additionalProperties: true description: First sample to compare title: Sample A type: object sample_b: additionalProperties: true description: Second sample to compare title: Sample B type: object selection_components: anyOf: - additionalProperties: true type: object - type: 'null' description: Optional pair-selection diagnostics title: Selection Components selection_policy: anyOf: - type: string - type: 'null' description: Pair selection policy identifier used for this pair title: Selection Policy selection_score: anyOf: - type: number - type: 'null' description: Selection utility score for this pair title: Selection Score submit_ready: default: true description: True when this pair ID is already accepted by vote submission. title: Submit Ready type: boolean vote_cost_credits: default: 1 description: Credits required to vote this pair (0 for exam) minimum: 0 title: Vote Cost Credits type: integer required: - sample_a - sample_b - pair_id title: NextPairResponse type: object SessionProgressResponse: description: Progress information for anonymous voter. properties: audience: default: public enum: - public - internal title: Audience type: string experiment_name: title: Experiment Name type: string instructions: anyOf: - type: string - type: 'null' title: Instructions is_authenticated: default: false title: Is Authenticated type: boolean login_required: default: false title: Login Required type: boolean max_votes: anyOf: - type: integer - type: 'null' title: Max Votes participant_label: anyOf: - type: string - type: 'null' title: Participant Label participant_mode: anyOf: - enum: - anonymous - transferred - authenticated - linked_requires_login type: string - type: 'null' title: Participant Mode participant_required: default: false title: Participant Required type: boolean session_name: title: Session Name type: string votes_cast: title: Votes Cast type: integer required: - votes_cast - max_votes - session_name - experiment_name title: SessionProgressResponse type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: BearerAuth: bearerFormat: Supabase JWT scheme: bearer type: http ApiKeyAuth: in: header name: X-API-Key type: apiKey ````