Documentation/Getting started
Arcane Public API
A read-oriented HTTP/JSON API exposing player profiles, leaderboards, aggregate statistics and supporter data for the Arcane Minecraft network. No key required for the public surface.
What this is
The Arcane network runs a Minecraft Java server behind a Velocity proxy with several game modes — Rush, League, Arène PvP, HikaBrain, FreeCube and a seasonal Clicker. Game state is persisted to a relational database and projected through a JSON API that the website and the in-game clients consume.
This documentation covers that API as observed from the public internet. It is the same data the official site renders — nothing here requires elevated access.
Design conventions
- JSON everywhere. Every response is
application/json; charset=utf-8, including errors.
- Snake_case fields. Regardless of the language the backing service is written in, the wire format is snake_case.
- Unix milliseconds for timestamps.
premier_join and dernier_join are integer epoch milliseconds, not seconds, not ISO 8601.
- Seconds for durations. Any field ending in
_temps_secondes is a duration in seconds.
- Wrapped collections. List endpoints return
{"data": [...]} plus pagination metadata, never a bare array.
- French domain vocabulary.
niveau is level, morts is deaths, parties is matches, victoires is wins, arcanites is the premium currency.
Quick start
# health check
curl https://api.arcanemc.eu/api/health
# one player by page position
curl "https://api.arcanemc.eu/api/players?limit=1"
# top of the leaderboard
curl "https://api.arcanemc.eu/api/leaderboard?limit=10"
Documentation/Getting started/Base URL & access
Base URL & access
Three independently deployed services share the arcanemc.eu zone. They are separate origins with separate behaviour — do not assume one accepts what another does.
Origins
▸
Transport. HTTPS only. Plain HTTP is not served. The public API and the main site advertise Strict-Transport-Security: max-age=31536000; the shop origin does not, so do not depend on HSTS for it.
CORS
The public API applies a strict origin allowlist. It echoes Access-Control-Allow-Origin only for the canonical web origins, and falls back to no header otherwise — it never returns a wildcard.
Preflight is answered for GET, OPTIONS with Accept, Content-Type permitted. Any other method is not advertised.
Methods
Public routes are read-only. GET and OPTIONS succeed; PUT, PATCH, DELETE and TRACE return 404 or 405 depending on the route. There is no batch or bulk endpoint.
Documentation/Getting started/Authentication
Authentication
The public API is entirely unauthenticated. The shop API is unauthenticated for catalogue reads. The manager API is session-based with mandatory TOTP.
Public API — no credentials
Every route under api.arcanemc.eu/api/ is readable without a key, token, cookie or header. There is no API-key system, no OAuth flow and no signed-URL requirement. Rate limiting is per-IP only.
Shop API — no credentials
Catalogue and checkout-configuration reads are open. Creating a checkout basket requires no session either — the shop trusts the pseudo you submit after validating it against the player table.
Manager API — session + TOTP
The staff panel uses a cookie session with a TOTP second factor. Relevant routes:
POST /auth/login login + password
POST /auth/logout destroy session
POST /auth/mfa/verify submit TOTP code
POST /auth/mfa/setup begin TOTP enrolment
POST /auth/mfa/setup/confirm confirm enrolment
!
Failure behaviour. A bad credential returns 401 {"error":"Identifiants incorrects"} with an identical body for existing and non-existent accounts, so the endpoint does not disclose account existence. A missing field returns 400 {"error":"Champs manquants"}.
Unauthenticated requests to protected data routes return 401 {"error":"Non authentifié"}. Forwarding headers such as X-Forwarded-For, X-Real-IP, X-Original-URL and X-Rewrite-URL have no effect on authorisation.
Documentation/Getting started/Rate limiting
Rate limiting
Limits are per-IP, fixed-window, and reported in headers on every response. Exceeding the budget returns 429 with a JSON body rather than an empty response.
Budgets by service
HTTP/2 200
x-ratelimit-limit: 120
x-ratelimit-remaining: 49
Decrement x-ratelimit-remaining and back off before it reaches zero. Because the window is fixed rather than sliding, a burst immediately after a reset can consume the whole budget in under a second.
Practical guidance
- Pace to roughly 1.5 requests/second to stay inside 120 per minute with headroom.
- Honour
Retry-After when present; otherwise sleep 60 seconds on a 429.
- Cache aggressively — player data changes on game events, not per request. An
ETag is provided for conditional fetches.
- A full player-table sync is 80 requests at
limit=61. Budget accordingly.
▸
Page size ceiling. limit is silently clamped to 61. Requesting limit=100000 returns 61 rows, not an error — always compare data.length against your requested limit when computing page counts.
Documentation/Getting started/Errors & status codes
Errors & status codes
Errors are JSON objects with a single error key holding a short machine-readable slug. There is no nested error envelope, no error codes registry and no request id.
Error shape
{
"error": "not_found"
}
Status codes
Validation messages
!
Unmatched shop routes fall through to Express. Requesting an unknown path under boutique.arcanemc.eu/api/ returns an HTML Cannot GET /api/… page with a 200-family HTML content type, not JSON. Treat any non-JSON response as a routing miss rather than a valid reply.
Documentation/Public endpoints/Health
Health
GET /api/health liveness probe
Returns a constant success object when the API process is serving. It does not check the database, the game servers or any downstream dependency.
Request
curl https://api.arcanemc.eu/api/health
Response
HTTP/2 200
content-type: application/json; charset=utf-8
{ "ok": true }
Fields
▸
Not a readiness probe. The endpoint answers even when the database is unreachable, so a 200 here does not mean player data is trustworthy. Probe /api/stats for a real read-path check.
Documentation/Public endpoints/Players
Players
GET /api/players paginated player profiles + search
The primary dataset. Returns player profiles across all game modes, ordered by level descending by default. Each record carries 58 fields spanning identity, economy, progression and per-mode statistics.
Query parameters
Unknown parameters are ignored. sort, order and rank have no effect — ordering is fixed at level descending.
Example
curl "https://api.arcanemc.eu/api/players?limit=2&page=1"
Response
{
"data": [
{
"uid": "3d7f9a35-4516-4066-87e9-981520653322",
"pseudo": "edoustrizz",
"rank_id": "MINI_VIP",
"rank_label": "Mini-VIP",
"rank_color": "#5555FF",
"niveau": 66,
"xp": 553736,
"arcanites": 65,
"runes": 14221,
"kills_totaux": 8304,
"premier_join": 1792333966615,
"dernier_join": 1795001632253,
"dernier_backend": "rush",
"online": 0,
"serveur": null
}
],
"total": 4796,
"page": 1,
"limit": 2
}
Each element of data is a full Player object — the example above is abridged for readability; the wire response contains all 58 fields.
Search behaviour
search is a substring match, not a prefix match, so search=z returns any pseudo containing a z. Results remain ordered by level descending across the whole filtered set — total reflects the filtered count.
curl "https://api.arcanemc.eu/api/players?search=zZzZz"
// -> total reflects only matching pseudos
▸
Full-table sync. With total = 4796 and a 61-row ceiling, a complete snapshot is 80 requests. At the 120/minute budget that is well inside a single window, but assume it takes two.
Documentation/Public endpoints/Leaderboard
Leaderboard
GET /api/leaderboard ranked player list
Same player objects as /api/players, ordered by rank. Intended for the top-N view; use /api/players for bulk sync.
Query parameters
Example
curl "https://api.arcanemc.eu/api/leaderboard?limit=3"
Response
{
"data": [
{
"uid": "1aaf631e-d188-497a-adee-66a8a10c7ab5",
"pseudo": "Bourmon",
"rank_id": "ADMINISTRATEUR",
"rank_label": "Owner",
"rank_color": "#FF5555",
"niveau": 974,
"xp": 118743580,
"arcanites": 90244,
"runes": 27263,
"rush_ranked_elo": 74,
"rush_ranked_peak_elo": 100,
"arene_best_streak": 1
}
]
}
No pagination metadata is returned — this is a top-N projection. Each element is still a complete Player object.
!
Rank is not skill. Ordering is driven by account level, and administrator accounts accrue level from development activity rather than play. Filter by rank_id if you need a competitive view, and use the per-mode fields (rush_ranked_elo, arene_best_streak) for performance ranking.
Documentation/Public endpoints/Statistics
Statistics
GET /api/stats network-wide aggregates
A single object of network-wide counters. Cheap to poll, useful as a liveness and read-path check.
Request
curl https://api.arcanemc.eu/api/stats
Response
{
"total_players": 4796,
"online_players": 10,
"graded_players": 131,
"games_played": 815,
"total_kills": 608855,
"total_playtime": 169165775,
"total_arcanites": 1180055
}
Fields
▸
Derived value. total_arcanites is the sum of arcanites across all player records, so it moves whenever anyone spends in game. It is a stock, not a revenue figure — currency already spent is excluded.
Documentation/Public endpoints/Contributors
Contributors
GET /api/contributors supporters grouped by rank tier
Returns grade holders grouped by tier, intended for the "Contributeurs" panel on the website. Includes custom per-player rank labels and colours.
Request
curl https://api.arcanemc.eu/api/contributors
Response
{
"groups": [
{
"rank_id": "PERSO",
"label": "Perso",
"color": "#FFAA00",
"members": [
{
"uid": "5ce0e416-fd52-4d58-a92d-7cb20594b6cf",
"pseudo": "RojNika",
"rank_id": "PERSO",
"niveau": 92,
"online": 0,
"rank_label": "✴",
"rank_color": "#FF55FF"
}
]
}
],
"total": 96
}
Response fields
Member object
Members are a projection of the full Player object: only uid, pseudo, rank_id, niveau, online, rank_label and rank_color are present. Fetch /api/players for the full record.
Observed tiers
!
MINI_VIP is excluded. MINI_VIP holders appear in /api/players but are absent from this endpoint — by the site's own classification it is not a supporter tier. Do not assume the two datasets agree.
Documentation/Reference/Player object
Player object
The core data structure. 58 fields: identity, economy, progression, and per-mode statistics for six game modes. Every field is present on every record; absent values are null rather than omitted.
Shape
{
"uid": "866f2e15-c411-43b2-b24f-26bd6731b45f",
"pseudo": "AceOlip",
"rank_id": "PERSO",
"rank_label": "✴",
"rank_color": "#FF55FF",
"rank_prefix": [
{ "text": "✴", "color": "#FFFF55", "bold": true }
],
"niveau": 36,
"xp": 173415,
"arcanites": 0,
"runes": 31160,
"kills_totaux": 1854,
"temps_total_secondes": 266475,
"premier_join": 1792333966615,
"dernier_join": 1795001632253,
"dernier_backend": "rush",
"online": 1,
"serveur": "arene-pvp",
"arene_kills": 1854,
"arene_morts": 1200,
"arene_best_streak": 130,
"arene_streak": 0,
"arene_kd": 1.55,
// … rush_*, lg_*, hikabrain_*, freecube_* fields
}
Identity & progression
Economy
Presence & activity
Per-mode fields
Five modes expose statistics. Each follows the same naming convention — {mode}_{metric} — except HikaBrain and FreeCube, which deviate in a few places.
Derived fields
{mode}_kd and {mode}_winrate are computed server-side, not stored. They are floats and may be 0 when the denominator is zero rather than null:
"arene_kd": 1.55, // 1854 kills / 1200 deaths
"rush_kd": 0, // no deaths recorded — reports 0, not null
"rush_vd": 0 // victories / defeats ratio
Tier objects
rush_tier, lg_tier and hikabrain_tier are objects, not strings:
"rush_tier": {
"min": 0,
"roman": "I",
"color": "#868e96"
}
Documentation/Reference/Field dictionary
Field dictionary
Every field the API emits, alphabetised, with type and semantics. If a field is not listed here it is not part of the contract.
All 58 fields
!
No rank expiry field exists. Nothing in this schema records when a rank was granted, how long it lasts, or when it lapses. Rank duration is not exposed by any public endpoint — treat every rank_id as "held at request time" only.
Documentation/Reference/Rank tiers
Rank tiers
Sixteen distinct rank_id values are issued. Staff tiers are administrative; supporter tiers are commercial or granted; PERSO is a hand-configured personal tier.
Staff tiers
Supporter tiers
Other
Custom labels
PERSO holders carry a per-account rank_label: single glyphs or short words such as ✴, ✦, ツ, 💤. These are configured individually, so do not hardcode a label for the tier — always read rank_label from the player object.
Duration
!
No duration is published. There is no expiry, renewal or grant timestamp anywhere in the API. Season-podium rewards are time-limited by game configuration (30 days), but the API cannot tell you which accounts are on that clock. If you need expiry, you need a server-side source that is not this API.
Documentation/Reference/Pagination
Pagination
Offset pagination with a hard page-size ceiling. Simple to implement, but the ceiling is silent — plan for it.
Model
?page=N&limit=M, both 1-based for page. Metadata echoes back:
{
"data": [ /* up to 61 rows */ ],
"total": 4796,
"page": 1,
"limit": 61
}
The ceiling
Invalid values fall back to the default rather than erroring. Always compute page count from the limit echoed in the response, not the one you sent.
Correct sync loop
const BASE = "https://api.arcanemc.eu/api/players";
async function syncAll() {
const rows = [];
let page = 1, total = 0, effLimit = 61;
while (true) {
const res = await fetch(`${BASE}?page=${page}&limit=61`);
if (res.status === 429) { await sleep(60000); continue; }
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
total = body.total;
effLimit = body.limit;
rows.push(...body.data);
if (rows.length >= total || body.data.length === 0) break;
page++;
await sleep(700); // stay under 120 req/min
}
return { rows, total, pages: page, effLimit };
}
const sleep = ms => new Promise(r => setTimeout(r, ms));
▸
Offsets drift. Because ordering is by mutable niveau, rows can shift between pages during a long sync. De-duplicate on uid when assembling the final set — a full sync may return more unique rows than total.
Documentation/Other surfaces/Shop API
Shop API
The storefront at boutique.arcanemc.eu. Sells premium currency and two moderation-clearing services through Tebex Headless checkout. Catalogue reads are unauthenticated.
Catalogue
GET /api/packages currency packs
{
"currency": "EUR",
"ready": true,
"packs": [
{ "id": "arc-500", "eur": 5, "arcanites": 500, "bonusPct": 0, "popular": false, "bestValue": false, "buyable": true },
{ "id": "arc-1100", "eur": 10, "arcanites": 1100, "bonusPct": 10, "popular": false, "bestValue": false, "buyable": true },
{ "id": "arc-2400", "eur": 20, "arcanites": 2400, "bonusPct": 20, "popular": true, "bestValue": false, "buyable": true },
{ "id": "arc-4550", "eur": 35, "arcanites": 4550, "bonusPct": 30, "popular": false, "bestValue": false, "buyable": true },
{ "id": "arc-7000", "eur": 50, "arcanites": 7000, "bonusPct": 40, "popular": true, "bestValue": false, "buyable": true },
{ "id": "arc-15000", "eur": 100, "arcanites": 15000, "bonusPct": 50, "popular": false, "bestValue": true, "buyable": true }
]
}
Effective rates
Services
GET /api/services non-currency products
{
"currency": "EUR",
"services": [
{ "id": "svc-liberation", "nom": "Libération des chaînes", "eur": 20, "buyable": true },
{ "id": "svc-demute", "nom": "Démute", "eur": 5, "buyable": true }
]
}
Player lookup
GET /api/player/{pseudo} existence + balance
// known account
{ "known": true, "pseudo": "edoustrizz", "arcanites": 65 }
// unknown account
{ "known": false, "pseudo": "NonExistent" }
The pseudo is validated before lookup; illegal characters return {"error":"pseudo invalide"}. Responses are rate limited at roughly 50 per window.
Checkout configuration
GET /api/checkout-config?item={id} basket endpoints for an item
{
"basketsUrl": "https://headless.tebex.io/api/accounts/{token}/baskets",
"packagesBaseUrl": "https://headless.tebex.io/api/baskets",
"accountBasketUrl": "https://headless.tebex.io/api/accounts/{token}/baskets",
"packageId": 7563868,
"completeUrl": "https://boutique.arcanemc.eu/success",
"cancelUrl": "https://boutique.arcanemc.eu/cancel"
}
The parameter is item and accepts a pack id or a service id. Unknown values return {"error":"pack inconnu"}. The response maps the shop item onto a Tebex package — pricing lives in Tebex, not here.
Create checkout
POST /api/checkout mint a basket URL
curl -X POST https://boutique.arcanemc.eu/api/checkout \
-H "Content-Type: application/json" \
-d '{"packId":"arc-500","pseudo":"edoustrizz"}'
// 200
{ "url": "https://pay.tebex.io/dyqlq7-f7ebc97d93ff9783b940ef574161268504609c34" }
Request body
✓
Price is server-side. Submitting eur or arcanites alongside packId has no effect — the amount is resolved from the package mapping, not the request. Do not build a client that sends them.
Tebex catalogue
The underlying Tebex Headless API is publicly readable with the account token returned by /api/checkout-config:
# categories
curl "https://headless.tebex.io/api/accounts/{token}/categories"
# categories with packages inline
curl "https://headless.tebex.io/api/accounts/{token}/categories?includePackages=1"
Package objects include base_price, total_price, currency, type (single or subscription), and expiration_date. Verified live: the catalogue holds only the six currency packs and the two services above. No rank product exists.
!
Ranks are not sold here. Despite the site referring to "grades boutique", no VIP/MVP/PERSO product exists on the web shop or in the Tebex catalogue. Rank grants happen off-platform, and consequently no public endpoint exposes rank price or duration.
Documentation/Other surfaces/Manager API
Manager API
The staff panel backend. Every route below requires an authenticated session plus TOTP and returns 401 {"error":"Non authentifié"} otherwise. Documented for completeness of the surface map.
!
Authorisation is uniformly enforced. There is no public route under this host that returns data without a session. Verified across GET/POST/PUT/PATCH/DELETE and against forwarding-header spoofing.
Session
POST /auth/login credentials
POST /auth/logout end session
POST /auth/mfa/verify TOTP code
GET /api/me current session identity
POST /api/me/password rotate own password
Player management
GET /api/players list
GET /api/players/search search by pseudo
GET /api/players/{name}/full complete profile
GET /api/players/{name}/messages chat history
GET /api/players/{name}/skin skin render
Moderation
GET /api/sanctions/active currently applied
GET /api/sanctions/recent recent history
GET /api/sanctions/staff by issuing staff
GET /api/sanctions/manager by target manager
POST /api/players/{name}/sanction apply sanction
POST /api/players/{name}/unban lift ban
DELETE /api/sanctions/{id} revoke sanction
GET /api/moderation/reports player reports
GET /api/moderation/anticheat anticheat flags
DELETE /api/reports/{id} dismiss report
Staff management
GET /api/staff roster
GET /api/team public team view
GET /api/staff/{id} single member
PATCH /api/staff/{id}/role change role
POST /api/staff/{id}/reset reset credentials
GET /api/absences leave records
DELETE /api/absences/{id} delete record
Operations
GET /api/stats/overview dashboard metrics
GET /api/online live sessions
GET /api/connections/recent connection log
GET /api/audit audit trail
GET /api/vpn VPN/proxy detections
POST /api/vpn/sync refresh list
DELETE /api/vpn/{range}/{ip} remove entry
GET /api/personal per-user settings
Documentation/Other surfaces/Infrastructure
Infrastructure
Summary of the observed deployment topology. Included because clients need to know about edge behaviour, timeouts and versioning — not as an operator runbook.
Hosts
Observed stack
Game backends
Two backends are referenced by dernier_backend: rush and hub. Live per-server assignments appear in serveur — currently arene-pvp. Treat these as opaque identifiers; do not assume a fixed list.
Client guidance
- Set a request timeout of at least 10 seconds — cold reads occasionally exceed 2s.
- Retry idempotent
GETs on 5xx with exponential backoff; never retry a POST /api/checkout blindly, it mints a new basket each time.
- Expect the edge to add latency and occasionally return its own
5xx page rather than JSON — parse defensively.
- Do not pin to the origin IP. TLS is served with an edge certificate that will not match.
Documentation/Appendix/Code examples
Code examples
Working snippets against the live endpoints. All read-only; none require credentials.
curl
# single player
curl -s "https://api.arcanemc.eu/api/players?limit=1" | jq '.data[0] | {pseudo, niveau, arcanites}'
# search by pseudo
curl -s "https://api.arcanemc.eu/api/players?search=edous" | jq '.total'
# top 10
curl -s "https://api.arcanemc.eu/api/leaderboard?limit=10" | jq -r '.data[] | "\(.niveau)\t\(.pseudo)"'
# network counters
curl -s https://api.arcanemc.eu/api/stats | jq
# supporters by tier
curl -s https://api.arcanemc.eu/api/contributors | jq -r '.groups[] | "\(.rank_id): \(.members|length)"'
Python
import json, time, urllib.request, urllib.error
BASE = "https://api.arcanemc.eu/api"
UA = {"User-Agent": "my-app/1.0", "Accept": "application/json"}
def get(path, **params):
qs = "&".join(f"{k}={v}" for k, v in params.items())
url = f"{BASE}{path}" + (f"?{qs}" if qs else "")
req = urllib.request.Request(url, headers=UA)
for attempt in range(4):
try:
with urllib.request.urlopen(req, timeout=15) as r:
return json.load(r)
except urllib.error.HTTPError as e:
if e.code == 429:
time.sleep(60)
continue
raise
raise RuntimeError("rate limited")
def all_players():
out, page = [], 1
while True:
body = get("/players", page=page, limit=61)
out.extend(body["data"])
if len(out) >= body["total"] or not body["data"]:
break
page += 1
time.sleep(0.7)
return out
if __name__ == "__main__":
rows = all_players()
print(f"{len(rows)} players")
print(get("/stats"))
JavaScript
const BASE = "https://api.arcanemc.eu/api";
async function getPlayer(pseudo) {
const res = await fetch(
`${BASE}/players?search=${encodeURIComponent(pseudo)}&limit=1`,
{ headers: { Accept: "application/json" } }
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data } = await res.json();
const hit = data.find(p => p.pseudo.toLowerCase() === pseudo.toLowerCase());
return hit ?? null;
}
// Render an avatar from the uid — the client CDN accepts a UUID
const avatar = uid => `https://mc-heads.net/body/${uid}/right`;
TypeScript types
export interface Player {
uid: string;
pseudo: string;
rank_id: string;
rank_label: string;
rank_color: string;
rank_prefix: { text: string; color: string; bold?: boolean }[] | null;
niveau: number;
xp: number;
arcanites: number;
runes: number;
kills_totaux: number;
online: 0 | 1;
serveur: string | null;
dernier_backend: "rush" | "hub" | null;
premier_join: number; // epoch ms
dernier_join: number; // epoch ms
temps_total_secondes: number;
[mode: string]: unknown; // per-mode counters
}
export interface Paged<T> {
data: T[];
total: number;
page: number;
limit: number;
}
Documentation/Appendix/Changelog
Changelog
Revision history for this documentation. The API itself is unversioned — there is no version prefix in the path and no version negotiation header.
v1 — 18 November 2026
- Initial publication of the reference.
- Documented 5 public endpoints, 58 player fields, 16 rank tiers.
- Documented the shop surface: catalogue, player lookup, checkout configuration, basket creation.
- Documented the manager surface as an endpoint map (auth-gated, no payloads).
- Recorded observed limits: 120 req/min public, ~50 req/window shop lookup, 61-row page ceiling.
- Noted absence of rank expiry and rank pricing anywhere in the public surface.
Stability
!
No versioning contract. Nothing in the responses advertises a schema version. Treat field presence as guaranteed only for fields the official site itself renders, and ignore unknown fields rather than failing on them.