Votes

Submit Vote

Submit a pairwise comparison vote.

Uses atomic transaction with row-level locking to ensure:

  • All database changes succeed or fail together
  • Concurrent votes on same entities don't cause race conditions

Rate limited to prevent abuse (default: 100/minute).

Tier-cap enforcement (PLATFORM_AUDIT M17): authenticated users have a monthly-vote limit per their subscription plan. Anonymous voters are rate-limited at the IP layer (no per-user cap to enforce).

Raises: HTTPException 403: Monthly vote limit reached for the user's tier HTTPException 404: Ranking or entity not found HTTPException 400: Invalid winner_id HTTPException 409: Conflict due to concurrent modification HTTPException 500: Internal server error

post/api/v1/votes

Request

  • Base URL: https://app.aimrank.io (the document declares no server; this is the origin it was published from)
  • URL: https://app.aimrank.io/api/v1/votes
  • Auth: none declared

Request body

ranking_idstring required

UUID of the ranking

entity_a_idstring required

UUID of first entity

entity_b_idstring required

UUID of second entity

winner_idstring nullable

UUID of winner (null = draw/skip)

confidencenumber nullable

User confidence 0-1

decision_time_msinteger nullable

Time to decide (max 5 min)

sourcestring nullable

Vote source: organic, recommendation, embed, api

invite_codestring nullable

Invite code that grants access to a non-public ranking. Allows anonymous voting on private rankings when the code's access_type permits it.

idempotency_keystring nullable

Client-supplied key that makes this vote safely retryable. A retried / double-clicked submission carrying the same key applies the rating delta exactly once — the replay returns the original vote result (200) instead of creating a second vote. Omit for the default fire-and-forget behaviour.

voter_segmentobject nullable

Voter demographics for segment slicing — free-shape JSON object, e.g. {age_group: '25-34', gender: 'female', region: 'EU', role: 'designer'}. Persisted on the vote so leaderboards can be filtered by audience segment (marketing-agency use case). Max 16 keys, value strings ≤ 64 chars.

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.