Developer API

Build with AimRank API

Create rankings, collect votes, and get calibrated results, all via a RESTful API. Powered by six rating engines with adaptive matchmaking.

Interactive API Docs ReDoc Reference

Quick Start

Step 1

Sign up and sign in

Create a free account, then use the bearer token from POST /api/v1/auth/login. API keys come with paid plans, which are not open yet.

Step 2

Make your first request

Create a ranking, add entities, and submit your first vote.

Step 3

Get calibrated results

Ratings update in real-time using adaptive ranking algorithms.

Code Examples

List public rankings

curl -s https://app.aimrank.io/api/v1/rankings | python -m json.tool

Create a ranking & add entities

curl -X POST https://app.aimrank.io/api/v1/rankings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Best Programming Languages", "is_public": true, "category": "tech"}'

Submit a vote

curl -X POST https://app.aimrank.io/api/v1/votes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ranking_id": "RANKING_ID", "entity_a_id": "ID_A", "entity_b_id": "ID_B", "winner_id": "ID_A"}'

Embed Widgets

Embed a leaderboard or an entity badge on any website that accepts an iframe. Copy the code and paste it into your HTML.

Leaderboard Widget

Shows the ranked list as it stands when the page loads. Configurable theme and item limit.

<iframe
  src="https://app.aimrank.io/embed/RANKING_ID?type=leaderboard&theme=dark&limit=10"
  width="100%"
  height="400"
  frameborder="0"
  style="border-radius: 12px; overflow: hidden;"
></iframe>

Entity Badge

Display a single entity's rank and rating. Great for profile pages or sidebars.

<iframe
  src="https://app.aimrank.io/embed/RANKING_ID?type=badge&entity=ENTITY_ID&theme=dark"
  width="300"
  height="60"
  frameborder="0"
  style="border: none;"
></iframe>

Parameter	Values	Description
type	leaderboard \| badge	Widget type (default: leaderboard)
theme	dark \| light	Color theme (default: dark)
limit	1–50	Max entities shown (default: 10)
entity	ENTITY_ID	Entity ID for badge widget

Authentication

JWT Bearer Token

Authenticate via POST /api/v1/auth/login to get access and refresh tokens. Pass the access token in the Authorization header.

Authorization: Bearer eyJhbGciOi...

API Key (paid plans)

API keys come with paid plans, which are not open yet; a free account gets a 403 from POST /api/v1/api-keys. On a paid plan you create them under Account → API keys, scoped read, write or admin. New keys are read-only unless you grant more.

X-API-Key: ak_dGhpcyBpcyBhIHRl...

AI agents: no key needed to start

The public MCP endpoint is open to everyone, with no key and no account: 21 read-only tools over the public catalogue, any public ranking and its quality evidence. Voting, creating and exports live on the keyed endpoint (/mcp/mcp).

https://app.aimrank.io/mcp/public

Rate Limits

Default limits per client (per API key when you send one, otherwise per IP address).

Requests	Limit	Window
Reads (GET)	600	per minute
Writes (POST, PUT, PATCH, DELETE)	120	per minute
Votes	100	per minute
Sign-in and sign-up	10	per minute

Over the limit you get HTTP 429 with a Retry-After header.

Full OpenAPI specification available at /openapi.json

Privacy · Terms · Home