API Docs

USL Open API

Public endpoints for levels, leaderboards, players, records and country statistics. Every response is JSON.

Base URL https://ultimateshittylist.space/api
Open access

No token or registration is required for any documented endpoint.

JSON everywhere

Every endpoint answers with a JSON body and the matching HTTP status code.

Rate limited

120 requests per minute per IP. Be kind and cache responses.

Levels

GET /api/levels

Full list of ranked levels with position, creator, verifier, difficulty and points.

Response example 
{
  "ok": true,
  "count": 2,
  "levels": [
    {
      "id": 1,
      "rank": 1,
      "name": "Shitty Grief",
      "creator": "icedcave",
      "verifier": "wPopoff",
      "difficulty": "Extreme",
      "requirement": 68,
      "points": 1000,
      "video_url": "https://www.youtube.com/watch?v=...",
      "banner_url": "/uploads/banners/...",
      "level_id": "110192585"
    }
  ]
}
GET /api/demons

Paginated plain-text level list, one level per line. Useful for Discord bots and terminal tools.

Parameters

page number

Page index, starts at 0 (default 0).

limit number

Levels per page, 1-100 (default 10).

Response example 
{
  "ok": true,
  "page": 1,
  "pages": 8,
  "count": 10,
  "total": 75,
  "levels": "1. #1 Shitty Grief (Extreme) - icedcave - 68% - Slaughterhouse\n2. #2 Shitty Flamewall (Extreme) - Narwall - 72% - Acheron"
}
GET /api/demons/:id

Single level with points, comparable Geometry Dash level and verified records.

Parameters

id number required

Numeric USL level id.

format string

Set to json to receive a JSON body instead of HTML.

Response example 
{
  "ok": true,
  "demon": {
    "id": 2,
    "position": 2,
    "name": "Shitty Flamewall",
    "creator": "Narwall",
    "verifier": "Zoink",
    "difficulty": "Extreme",
    "requirement": 72,
    "points": 960,
    "shittylist_equiv": "Acheron"
  },
  "records": [
    { "username": "Zoink", "progress": 100, "points": 960 }
  ]
}

Leaderboards

GET /api/leaderboard

Global player ranking by rating, with records, completions and hardest completion.

Response example 
{
  "ok": true,
  "count": 2,
  "players": [
    {
      "rank": 1,
      "id": 1,
      "username": "wPopoff",
      "registered": true,
      "country": "US",
      "score": 3720,
      "records": 6,
      "verifications": 2,
      "completions": 5,
      "hardest": "Shitty Grief"
    }
  ]
}
GET /api/players/:id

Player profile by numeric id with full record and verification lists.

Parameters

id number required

Numeric player profile id.

format string

Set to json to receive a JSON body instead of HTML.

Response example 
{
  "ok": true,
  "player": {
    "id": 1,
    "user_id": 3,
    "username": "wPopoff",
    "registered": true,
    "role": "admin",
    "country": "US",
    "rating": 3720,
    "rank": 1,
    "hardest": {
      "demon_id": 1,
      "demon_name": "Shitty Grief",
      "position": 1,
      "source": "verification"
    }
  },
  "records": [
    { "id": 12, "demon_id": 1, "demon_name": "Shitty Grief", "progress": 100, "points": 1000, "youtube_url": "https://youtu.be/..." }
  ],
  "verifications": [
    { "id": 1, "name": "Shitty Grief", "position": 1 }
  ]
}
GET /api/records

Latest verified records across all levels.

Parameters

limit number

Maximum records to return (default all).

Response example 
{
  "ok": true,
  "count": 2,
  "records": [
    {
      "id": 12,
      "player": "wPopoff",
      "level": "Shitty Grief",
      "progress": 100,
      "score": 1000,
      "video_url": "https://youtu.be/...",
      "platform": "PC",
      "created_at": "2026-07-01T12:00:00.000Z"
    }
  ]
}

Countries

GET /api/countries

Country ranking. Main mode sums every player score, unique mode counts each level once.

Parameters

mode string

main (default) or unique.

Response example 
{
  "ok": true,
  "mode": "main",
  "count": 2,
  "countries": [
    {
      "country": "US",
      "name": "United States",
      "flag": "🇺🇸",
      "rank": 1,
      "players": 12,
      "points": 12340.5,
      "unique_points": 5320,
      "unique_levels": 8
    }
  ]
}
GET /api/countries/:name

Single country with flag, rank and member players.

Parameters

name string required

ISO 3166-1 alpha-2 country code.

format string

Set to json to receive a JSON body instead of HTML.

Response example 
{
  "ok": true,
  "country": {
    "country": "US",
    "name": "United States",
    "flag": "🇺🇸",
    "rank": 1,
    "players": 12,
    "points": 12340.5,
    "members": [
      { "id": 1, "username": "wPopoff", "rating": 3720, "registered": true }
    ]
  }
}

Site

GET /api/position-history

Recent list movements: new levels, position changes and removals.

Parameters

limit number

Events to return, 1-200 (default 30).

Response example 
{
  "ok": true,
  "count": 30,
  "history": [
    {
      "id": 55,
      "event_type": "move",
      "demon_id": 3,
      "level_name": "Shitty Society",
      "old_position": 2,
      "new_position": 1,
      "reason": "New #1 verified",
      "actor_username": "admin",
      "is_primary": true,
      "created_at": "2026-07-02T10:00:00.000Z"
    }
  ]
}
GET /api/site-summary

Site statistics plus top players, top levels, latest records and news.

Response example 
{
  "ok": true,
  "stats": {
    "players": 120,
    "levels": 75,
    "records": 340,
    "countries": 32
  },
  "topPlayers": [
    { "rank": 1, "username": "wPopoff", "rating": 3720 }
  ],
  "topLevels": [
    { "id": 1, "rank": 1, "name": "Shitty Grief", "points": 1000 }
  ],
  "latestRecords": [
    { "player": "wPopoff", "level": "Shitty Grief", "progress": 100 }
  ],
  "latestNews": [
    { "id": 3, "title": "New #1 verified", "author": "admin" }
  ]
}