Developers

UniMate API · v1

Read endpoints for partners building on top of UniMate. JSON-only, versioned at /api/v1/*, authenticated by a single header.

One header

X-UniMate-API-Key

Read-only

GET endpoints. Write coming.

Rate-limited

Default 60/min · 10k/day per key

Versioned

/api/v1/* — locked surface

Authentication

Every request requires an API key issued by us. Send it as theX-UniMate-API-Keyheader (or Authorization: Bearer um_live_...). Keys look likeum_live_xxxxx…and are shown once at creation.

Want a key?

Email partnerships@getunimate.com with your use case. We typically reply same business day.

Quickstart

curl

curl https://getunimate.com/api/v1/health \
  -H "X-UniMate-API-Key: um_live_..."

Python

import httpx

KEY = "um_live_..."
r = httpx.get(
    "https://getunimate.com/api/v1/health",
    headers={"X-UniMate-API-Key": KEY},
)
print(r.json())

Node

const KEY = "um_live_...";
const r = await fetch("https://getunimate.com/api/v1/health", {
  headers: { "X-UniMate-API-Key": KEY },
});
console.log(await r.json());

Endpoints

GET/api/v1/health key required

Echoes your key prefix + rate limits. Use to verify integration.

Example response

{
  "status": "ok",
  "version": "1.0.0",
  "your_key": "um_live_aB3F",
  "rate_limit_per_min": 60,
  "rate_limit_per_day": 10000
}

GET/api/v1/stats key required

Aggregate counts: users, active 30d, universities, decks, AI messages, study rooms.

Example response

{
  "total_users": 12453,
  "active_users_30d": 4321,
  "universities_count": 38,
  "flashcard_decks": 28940,
  "ai_messages_total": 1843200,
  "study_rooms_total": 8120,
  "generated_at": "2026-05-09T13:42:00Z"
}

GET/api/v1/universities?country_code=kz&limit=50 key required

List universities. Filter by ISO alpha-2 country code. Sorted by student count.

Example response

[
  {
    "id": "0c4e2fb4-…",
    "name": "Kazakh-British Technical University",
    "short_name": "KBTU",
    "city": "Almaty",
    "country": "KZ",
    "country_code": "kz",
    "student_count": 5420,
    "is_verified": true,
    "default_academic_system": "semester_2",
    "default_gpa_scale": "100"
  },
  …
]

GET/api/v1/universities/{uni_id} key required

Full record for one university.

GET/api/v1/users/{nickname}/public key required

Public profile — nickname, first_name, avatar, bio, xp, tier, joined_at. No PII.

Example response

{
  "nickname": "alex_uni",
  "first_name": "Alex",
  "avatar_url": null,
  "bio": "CS @ KBTU · year 3 · grinder",
  "xp": 14820,
  "premium_tier": "plus",
  "joined_at": "2026-02-12"
}

GET/api/v1/leaderboards/global?limit=50 key required

Global top-N by XP. rank/nickname/first_name/xp/streak. Anonymous to non-active users.

GET/api/v1/leaderboards/university/{uni_id}?limit=50 key required

Top-N inside a single university. Same shape as global.

GET/api/v1/holidays/{country_code} key required

Public holidays + multi-day study breaks for KZ + RU (others on request).

Example response

[
  {
    "on_date": "2026-03-21",
    "name": "Наурыз мейрамы / Nauryz",
    "is_break": true,
    "description": "Spring equinox · multi-day"
  }
]

Rate limits

Default per-key: 60 requests / minute and 10 000 requests / day. Exceeding either returns 429 Too Many Requestswith a Retry-After header. Need higher limits — email us, we'll bump per-key.

Errors

401 — missing / invalid / revoked key
404 — resource not found (or not public)
429 — rate-limit hit, see Retry-After
5xx — our problem; retry with backoff

Public API surface is intentionally narrow. Write endpoints (tasks/notes for partner-side tools) coming Q3. Subscribe at /changelog for changes.