Developer API
Integrate Hytale username data directly into your applications.
Base URL: https://hytaleservers.it/names
1. Availability Check
GETLightweight proxy for realtime checks. Use this for "as-you-type" verification. It checks the local cache first, then the upstream API.
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | YES | Alphanumeric string (3-16 chars). |
{
"username": "RareName",
"available": true,
"cached": false
}
Scenario 2: Username Taken
{
"username": "Hytale",
"available": false,
"taken": true,
"uuid": "c0b1...",
"avatar": "https://...",
"cached": true
}
Scenario 3: Error (Invalid Format)
{ "error": "Invalid username format" }
2. Full Profile Details
GETRetrieves extensive player data including skin configuration, username history, rarity stats, and related names. This endpoint also updates the database.
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | YES | Target username to lookup. |
{
"username": "Noxy",
"uuid": "23be131a-11c9-46c6-9e58-4fd1e9d0eef7",
"avatar": "https://crafthead.net/hytale/avatar/...",
"skin_data": {
"haircut": "hair_color_variant",
"eyes": "eye_color_variant",
"face": "face_variant"
},
"name_history": [
{
"username": "Noxy",
"is_current": 1,
"first_seen_at": "2023-01-01"
}
],
"views": 1250,
"taken": 1,
"checked_at": "2025-01-27 15:30:00"
}
Scenario 2: Username Available (Not Found in DB/API)
{
"available": true,
"username": "UnknownPlayer",
"message": "This username is available!"
}
Limits & Status Codes
Information about usage quotas and common API responses.
| Limit Type | Description |
|---|---|
| Rate Limit | API calls are subject to upstream limits (PlayerDB). If you receive 429 Too Many Requests, please wait 60 seconds before retrying. |
| Code | Meaning |
|---|---|
| 200 OK | Success |
| 400 Bad Request | Invalid parameters |
| 429 Too Many Requests | Rate limit exceeded |
| 503 Service Unavailable | API connection error |