Developer API

Integrate Hytale username data directly into your applications.

Base URL: https://hytaleservers.it/names

1. Availability Check

GET

Lightweight proxy for realtime checks. Use this for "as-you-type" verification. It checks the local cache first, then the upstream API.

GET /api_proxy.php?username={name} Open Example
ParameterTypeRequiredDescription
username string YES Alphanumeric string (3-16 chars).
Scenario 1: Username Available
{ "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

GET

Retrieves extensive player data including skin configuration, username history, rarity stats, and related names. This endpoint also updates the database.

GET /get_profile.php?username={name} Open Example
ParameterTypeRequiredDescription
username string YES Target username to lookup.
Scenario 1: Full Profile Response
{ "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 TypeDescription
Rate Limit API calls are subject to upstream limits (PlayerDB). If you receive 429 Too Many Requests, please wait 60 seconds before retrying.

CodeMeaning
200 OKSuccess
400 Bad RequestInvalid parameters
429 Too Many RequestsRate limit exceeded
503 Service UnavailableAPI connection error