Rankings

Create Ranking

Create a new ranking.

post/api/v1/rankings

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/rankings
  • Auth: API key in header X-API-Key

Request body

namestring required
descriptionstring nullable
image_urlstring nullable

Ranking thumbnail URL (used in OG cards + leaderboard header)

is_publicboolean
visibilitystring nullable

Three-state visibility. Overrides is_public when provided.

tenant_idstring nullable

Owning org. Required if visibility=org_private.

categorystring nullable
media_typestring nullable
comparison_promptstring nullable

Question shown above every matchup. Default 'Which is better?'. Reframe pairwise voting for any binary-label task: 'Which is correct?', 'Which is on-brand?', 'Which is AI-generated?'. Same Glicko-2/Bradley-Terry math; only the prompt + interpretation change.

vote_typestring nullable

Voting primitive. 'pairwise' (default) shows two entities and the comparison_prompt as a comparison. 'binary' shows ONE entity at a time and the comparison_prompt as a yes/no — for moderation, fact-check, dataset labelling.

ends_atstring date-time nullable

Auto-close deadline for A/B-style tests. After this time votes are rejected (410 Gone) but the leaderboard stays readable. NULL = evergreen (default).

goalstring nullable

What the creator wants to learn. When set + ends_at passes, an LLM report is generated automatically. Well-stated goals produce sharper reports — be specific.

min_raters_per_pairinteger nullable

Minimum distinct voters per (entity_a, entity_b) pair before the pair counts towards IAA + RLHF export. Default 1 (any vote counts); AI-lab buyers typically use 3+.

qualification_requiredboolean nullable

If True, voters must clear the qualification gold-standard set before their votes count. Anonymous voting is implicitly disabled.

qualification_pass_thresholdnumber nullable

Pass-rate threshold on qualification items, default 0.80.

judge_modestring nullable
default_judge_modelstring nullable
settingsobject nullable

Response

Successful Response

idstring required
slugstring nullable
namestring required
descriptionstring nullable required
is_publicboolean required
visibilitystring
tenant_idstring nullable
categorystring nullable required
owner_idstring required
entity_countinteger required
vote_countinteger required
created_atstring date-time required
updated_atstring date-time required
user_rolestring nullable
media_typestring nullable
comparison_promptstring
vote_typestring
ends_atstring date-time nullable
goalstring nullable
min_raters_per_pairinteger
qualification_requiredboolean
qualification_pass_thresholdnumber
judge_modestring
default_judge_modelstring nullable

Changes

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