---
title: "Create Ranking"
method: POST
path: "/api/v1/rankings"
tags: ["Rankings"]
---

# Create 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`

Create a new ranking.

## Request body

- RankingCreate
  - `name` string, required
  - `description` string, nullable
  - `image_url` string, nullable: Ranking thumbnail URL (used in OG cards + leaderboard header)
  - `is_public` boolean
  - `visibility` string, nullable: Three-state visibility. Overrides is_public when provided.
  - `tenant_id` string, nullable: Owning org. Required if visibility=org_private.
  - `category` string, nullable
  - `media_type` string, nullable
  - `comparison_prompt` string, 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_type` string, 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_at` string, 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).
  - `goal` string, 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_pair` integer, 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_required` boolean, nullable: If True, voters must clear the qualification gold-standard set before their votes count. Anonymous voting is implicitly disabled.
  - `qualification_pass_threshold` number, nullable: Pass-rate threshold on qualification items, default 0.80.
  - `constitution` unknown[], nullable: Optional list of explicit principles voters apply when judging — list of strings or {id,text,category} dicts. Overrides domain-level constitution if set.
    - unknown
  - `objectives` unknown[], nullable: Optional evaluation axes — list of strings or {id,name,description,scale} dicts. Declarative; per-axis voting is v2.
    - unknown
  - `judge_mode` string, nullable
  - `default_judge_model` string, nullable
  - `settings` object, nullable

## Response `201`

Successful Response

- RankingResponse
  - `id` string, required
  - `slug` string, nullable
  - `name` string, required
  - `description` string, nullable, required
  - `is_public` boolean, required
  - `visibility` string
  - `tenant_id` string, nullable
  - `category` string, nullable, required
  - `owner_id` string, required
  - `entity_count` integer, required
  - `vote_count` integer, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `user_role` string, nullable
  - `media_type` string, nullable
  - `comparison_prompt` string
  - `vote_type` string
  - `ends_at` string, date-time, nullable
  - `goal` string, nullable
  - `min_raters_per_pair` integer
  - `qualification_required` boolean
  - `qualification_pass_threshold` number
  - `judge_mode` string
  - `default_judge_model` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/aimrank/apis/aimrank-api.md) · [All operations](https://skmtc.dev/aimrank/apis/aimrank-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aimrank/apis/aimrank-api/revisions/3574d0aff459?raw)