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
},
"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 |
/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.
/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