API Developers
Public API documentation for Hadaria
Base URL
https://hadaria.netAuthentication
No API key required
Response Format
All responses follow a uniform envelope format. The data field is always present.
Success (2xx)
{ "data": { ... } }Error (4xx/5xx)
{
"error": {
"code": "player_not_found",
"message": "Player not found"
},
"data": null
}Endpoints
/api/minecraft/uuidResolve a Minecraft UUID
Look up a player's UUID and canonical username from their Minecraft username.
Query Parameters
| Name | Type | Description |
|---|---|---|
username* | string | 3-16 chars, alphanumeric + underscore |
Success Response
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"username": "Falistos"
}
}Errors
| Status | Code | Message |
|---|---|---|
| 400 | invalid_username | Invalid username |
| 404 | player_not_found | Player not found |
Cached for 1 hour (stale-while-revalidate 24h).
/api/vote/statusGet vote status
Check a player's vote statistics and cooldown timers for each vote site.
Query Parameters
| Name | Type | Description |
|---|---|---|
username* | string | 3-16 chars, alphanumeric + underscore |
Success Response
{
"data": {
"sites": [
{
"siteId": 1,
"canVote": true,
"remainingMs": null
}
],
"stats": {
"today": 3,
"totalSites": 1,
"monthly": 45,
"total": 312
},
"dailyLimit": {
"limit": 16,
"remaining": 13,
"resetMs": 43200000
},
"boost": {
"active": true,
"multiplier": 3,
"bannerText": "x3 votes jusqu'au 15 !"
}
}
}Errors
| Status | Code | Message |
|---|---|---|
| 400 | invalid_username | Invalid username |
| 400 | ip_unavailable | Unable to determine IP address |
| 404 | player_not_found | Player not found |
remainingMs per site is the cooldown timer only. dailyLimit is present when the daily vote cap is enabled and contains the max (limit), votes left today (remaining), and time until midnight reset (resetMs). The daily counter resets at midnight in the server's configured display timezone.
/api/vote/submitSubmit a vote
Validate a vote after the player has voted on the external site. The server verifies the vote before recording it.
Request Body (JSON)
| Field | Type | Description |
|---|---|---|
username* | string | 3-16 chars, alphanumeric + underscore |
siteId* | integer | Vote site ID (currently: 1) |
Success Response
{
"data": {
"remainingMs": 5400000
}
}Error Example
{
"error": {
"code": "voted_recently",
"message": "Vote cooldown active"
},
"data": {
"remainingMs": 5400000
}
}Errors
| Status | Code | Message |
|---|---|---|
| 400 | invalid_request | Invalid JSON body / Invalid request body |
| 400 | vote_not_verified | Vote not detected on external site |
| 400 | voted_recently | Vote cooldown active |
| 400 | daily_limit_reached | Daily vote limit reached for this player |
| 400 | ip_unavailable | Unable to determine IP address |
| 404 | player_not_found | Player not found |
| 404 | vote_site_not_found | Vote site not found |
| 500 | vote_failed | Failed to submit vote |
| 503 | vote_temporarily_unavailable | Vote service temporarily unavailable |
The voted_recently error includes data.remainingMs with the cooldown time. The daily_limit_reached error includes data.dailyResetMs with the time until the daily counter resets at midnight in the server's configured display timezone.
/api/tebex/playerLook up a Tebex player
Resolve a Minecraft username to a Tebex player ID for gift purchases.
Query Parameters
| Name | Type | Description |
|---|---|---|
username* | string | 3-16 chars, alphanumeric + underscore |
Success Response
{
"data": {
"id": "12345",
"username": "Falistos"
}
}Errors
| Status | Code | Message |
|---|---|---|
| 400 | invalid_username | Invalid username |
| 404 | player_not_found | Player not found |
| 404 | tebex_lookup_failed | Player not found on Tebex |
Cached for 1 hour (stale-while-revalidate 24h).
/api/tebex/subscriptionCheck subscription status
Check whether a player has an active subscription.
Query Parameters
| Name | Type | Description |
|---|---|---|
username* | string | 3-16 chars, alphanumeric + underscore |
Success Response
{
"data": {
"active": true,
"source": "tebex",
"tier": "full",
"nextPaymentDate": "2025-03-15",
"status": "active"
}
}Errors
| Status | Code | Message |
|---|---|---|
| 400 | username_required | Username is required |
Rate Limiting
All endpoints are rate-limited per IP on a 60-second window. Exceeding the limit returns HTTP 429.
| Endpoint | Limit |
|---|---|
POST /api/vote/submit | 30 req/min |
GET /api/vote/status | 20 req/min |
GET /api/minecraft/uuid | 20 req/min |
GET /api/tebex/subscription | 10 req/min |
Vote Sites
Available vote sites used by the vote/status and vote/submit endpoints.
| siteId | Name | Cooldown |
|---|---|---|
1 | Serveur-Prive.net | 90 min |
Notes
- Username validation: 3 to 16 alphanumeric characters + underscore
- Format: all responses are
application/json