API Docs — Astralyn

Start here

One request. Useful data.

All public endpoints return JSON. No authentication is required for public guild and leaderboard data. Use the catalog first when building an integration: it gives you the available modes, sort fields, record counts and canonical URLs.

01

Discover

Fetch /leaderboards to discover every mode and its available sorting options.

02

Fetch

Use the exact endpoint from the response. Full leaderboards are returned in one compressed response.

03

Cache

Cache catalog data for 60 seconds and full leaderboard data for 60–90 seconds.

Discover the API

curl https://astralyn.site/api/leaderboards

Node.js / browser

const catalog = await fetch('https://astralyn.site/api/leaderboards')
  .then(response => response.json());

const bedwars = catalog.leaderboards.find(board => board.id === 'bedwars');
const data = await fetch(`https://astralyn.site${bedwars.fullEndpoint}`)
  .then(response => response.json());

Python / requests

import requests

catalog = requests.get(
    "https://astralyn.site/api/leaderboards", timeout=10
).json()

board = next(item for item in catalog["leaderboards"]
             if item["id"] == "bedwars")
data = requests.get("https://astralyn.site" + board["fullEndpoint"], timeout=30).json()

Global rankings

Leaderboards for every mode.

The catalog is the source of truth. It currently includes 15 game ratings and guild rankings. Full endpoints return every row in rank order; the regular endpoint stays paginated for UI tables.

GET/leaderboardscatalog · counts · routes

Returns every available leaderboard, its total number of records, default sort, allowed sort fields and the full endpoint to use.

Example response

{
  "total": 16,
  "leaderboards": [{
    "id": "bedwars",
    "total": 983,
    "defaultSort": "bw_level",
    "fullEndpoint": "/api/leaderboards/bedwars/full"
  }]
}

GET/leaderboards/{board}/fullcomplete dataset

Returns all records for one board in one response. The compact default contains profile fields and the relevant metrics for that board. Add compact=0 for every player column.

Query	Description
sort	Any field listed in the catalog for this board.
history=1	Adds previous position and change. Disabled by default for speed.
search	Optional case-insensitive player or guild filter.
alliance=1	Player boards only: return alliance members.

Discord bot example

const url = 'https://astralyn.site/api/leaderboards/bedwars/full?sort=bw_level';
const payload = await fetch(url).then(r => r.json());
// payload.total === payload.rows.length; payload.pages === 1

GET/leaderboards/{board}paginated UI data

Compatible with the website table. Use it when you only need a small page instead of the entire dataset.

Query	Description
page	1-based page number.
limit	10, 100 or 250. Defaults to 100.
sort	Allowed board sort field.
search	Optional name or UUID filter.

GET/leaderboards/statusdatabase status

Returns player and guild row counts for the leaderboard database.

Loading live board catalog…

Astralyn data

Guild & player endpoints.

Use these endpoints for member lists, profiles, public guild information and search. UUIDs may be supplied with or without hyphens where applicable.

GET/guildguild snapshot

Returns the current Astralyn guild snapshot, members, roles and aggregate GEXP data.

GET/membersmember roster

Returns the current member roster with ranks, GEXP and activity fields.

GET/guildsknown guilds

Returns public guild records known to the application.

GET/staffstaff directory

Returns visible staff profiles, titles, links and current player presentation data.

GET/player/{uuid}player profile

Returns one player profile and its guild member context.

GET/search/{query}player search

Resolves a player by Minecraft username or UUID.

Progress & history

GEXP you can build on.

GEXP endpoints use the guild day boundary configured by Astralyn. Dates are returned in ISO-friendly formats; use the history endpoints for charts and trend views.

GET/gexpfull GEXP dashboard

Returns totals, daily/weekly/total leaders, history and member-level GEXP data. Optional date and days query parameters.

GET/gexp/dailydaily ranking

Returns the daily ranking for a date. Use ?date=YYYY-MM-DD and ?limit=100 or ?limit=all.

GET/gexp-historychart series

Returns aggregate daily GEXP history. Use ?days=30 to control the range.

GET/player-gexp-history/{uuid}player series

Returns one player's historical GEXP values. Optional ?days=30.

GET/top-daily · /top-weekly · /top-totalleader shortcuts

Small, convenient top-player responses for cards and notifications.

GET/player-of-weekweekly winner

Returns the current weekly leader or a 404 response when there is no data.

Content

News, settings & service health.

GET/news · /announcements · /news/{id}public content

Returns published news, announcements and one public article.

GET/site-settingspublic counters

Returns public site counters such as all-time tracked players.

GET/statusapplication sync

Returns the guild data sync state, latest sync and public provider metadata.

GET/service-statuslive infrastructure

Returns the public health view used by status.astralyn.site. It never exposes tokens or internal exception details.

Complete reference

Every route, in one place.

The table below is the contract used by the website and the Discord integration. Paths are relative to https://astralyn.site/api. Public GET routes do not require a token. Administrative writes are intentionally protected and are not part of the public bot API.

GET/skin-registrycosmetics

Returns the skin, cape and cosmetic registry used by profile and leaderboard cards.

Query	Type	Description
page	integer	Optional page number.
limit	integer	Rows per page, capped by the API.

GET/site-settingspublic settings

Returns safe, public counters and presentation settings. Secrets, API keys and internal configuration are never included.

GET/gexpdashboard payload

Returns the complete GEXP dashboard for the current guild period.

Query	Type	Description
date	YYYY-MM-DD	Day to inspect. Defaults to the current guild day.
days	integer	History window for trend data.

GET/gexp/dailydaily ranking

Returns ranked member GEXP for one day. Use ?date=2026-10-11&limit=100; limit=all is supported for exports.

GET/top-daily · /top-weekly · /top-totaltop 10 shortcuts

Small, stable arrays for notification embeds and compact dashboard cards. These are the cheapest endpoints to poll.

POST/resolve-playersbulk resolve

Accepts Content-Type: application/json. The response preserves input order and reports unresolved names without failing the entire request.

Request body

{
  "players": ["Notch", "069a79f4-44e9-4726-a5be-fca90e38aaf5"]
}

GET/news · /announcements · /news/{id}published content

Returns published news. /news/{id} returns one article; /announcements returns announcement-type posts only.

Query	Type	Description
page	integer	Page for the collection endpoints.
limit	integer	Number of posts to return.

GET/service-statusno-store telemetry

Runs live probes for the website, primary database, leaderboards database, Node worker, Hypixel configuration and storage. The visual status center at status.astralyn.site consumes this response. It is deliberately not cached.

Path variables

Use URL encoding for names and UUIDs. Player identifiers can be UUIDs with or without hyphens.

/player/{uuid}
/player/069a79f4-44e9-4726-a5be-fca90e38aaf5

/search/{query}
/search/Notch

HTTP status codes

Every response is JSON, including errors.

200  Success
400  Invalid query or body
401  Authentication required
404  Resource not found
422  Validation failed
429  Too many requests
500  Temporary server error
503  Dependency unavailable

Authentication boundary: all read-only guild, player, GEXP, news and leaderboard routes are public. News writes and Atlas worker commands require the existing server-side authentication and must never be placed in a browser or Discord client.

Response shape

Predictable JSON.

Full leaderboard

One payload, ready for local pagination in a Discord bot.

{
  "leaderboard": "bedwars",
  "full": true,
  "sort": "bw_level",
  "total": 983,
  "pages": 1,
  "rows": []
}

Paginated leaderboard

Use pages and total to build table controls.

{
  "leaderboard": "bedwars",
  "page": 1,
  "limit": 100,
  "total": 983,
  "pages": 10,
  "rows": []
}

Tip for Discord bots: load a full board once, keep it in a short-lived memory cache and paginate locally. Do not call the API again for every button press.

Production notes

Built for integrations.

INFOCaching & headers60–90 seconds

Stable public GET responses send cache headers. Full leaderboards are compact by default and compressed by the edge server. Search responses are intentionally not cached publicly.

INFOErrorsHTTP + JSON

Check the HTTP status before reading data. Errors use a small JSON object such as {"error":"..."}. Retry 503 responses with exponential backoff.

INFORate & etiquettebe a good citizen

Use the catalog and cache results. Avoid polling more often than once per minute unless a user explicitly requests a refresh.

Build withAstralyn.

One request. Useful data.

Leaderboards for every mode.

Guild & player endpoints.

GEXP you can build on.

News, settings & service health.

Every route, in one place.

Path variables

HTTP status codes

Predictable JSON.

Full leaderboard

Paginated leaderboard

Built for integrations.

Build with
Astralyn.