Developer API

Build with AimRank API

Create rankings, collect votes, and get calibrated results, all via a RESTful API. Powered by 5 ranking algorithms with adaptive optimization.

Interactive API Docs ReDoc Reference

Quick Start

Step 1

Get an API key

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 /api/v1/rankings | python -m json.tool

Create a ranking & add entities

curl -X POST /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 /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 live leaderboards or entity badges on any website. Just copy the iframe code and paste it into your HTML.

Leaderboard Widget

Show a live-updating ranked list of entities. 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

Create API keys from POST /api/v1/api-keys with scoped permissions (read, write, admin) and optional IP allowlisting.

X-API-Key: ak_dGhpcyBpcyBhIHRl...

Rate Limits

Tier	Limit	Window	Notes
Unauthenticated	30	per minute	Read-only endpoints
Authenticated (JWT)	100	per minute	All endpoints
API Key	1,000	per hour	Configurable per key

Webhooks

Subscribe to real-time events via webhooks. Payloads are signed with HMAC-SHA256 for verification.

Event	Description
vote.created	When a vote is submitted
entity.created	When an entity is added to a ranking
entity.rating_changed	When an entity rating changes significantly
ranking.created	When a new ranking is created
ranking.milestone	When a ranking hits 100, 1K, or 10K votes
leaderboard.changed	When the #1 position changes
user.achievement	When a user earns an achievement

Full OpenAPI specification available at /openapi.json

Privacy · Terms · Home