Skip to main content
The MojangAPI interface provides utilities for interacting with the Mojang API, allowing you to fetch player information, profiles, and manage skins.

​
Accessing MojangAPI

import gg.essential.api.EssentialAPI

val mojangAPI = EssentialAPI.getMojangAPI()

​
Player Lookups

​
getUUID

Retrieve a player’s UUID from their username. 
import java.util.UUID

val future = mojangAPI.getUUID("Notch")
future?.thenAccept { uuid: UUID ->
    println("UUID for Notch: $uuid")
}
Parameters:
  • name: String - The player’s username
Returns: CompletableFuture<UUID>? - A future that resolves to the player’s UUID, or null if the request fails Reference: Mojang API - Username to UUID

​
getName

Retrieve a player’s username from their UUID. 
import java.util.UUID

val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val future = mojangAPI.getName(uuid)

future?.thenAccept { name: String ->
    println("Username: $name")
}
Parameters:
  • uuid: UUID - The player’s UUID
Returns: CompletableFuture<String>? - A future that resolves to the player’s username, or null if the request fails Reference: Mojang API - Usernames to UUIDs

​
Player Profiles

​
getProfile

Retrieve the complete player profile including skin and cape information. 
val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val profile = mojangAPI.getProfile(uuid)

if (profile != null) {
    println("Player: ${profile.name}")
    println("UUID: ${profile.id}")
    
    // Access textures
    val textures = profile.textures
    val skinUrl = textures.textures?.skin?.url
    val capeUrl = textures.textures?.cape?.url
    
    println("Skin URL: $skinUrl")
    println("Cape URL: $capeUrl")
}
Parameters:
  • uuid: UUID - The player’s UUID
Returns: Profile? - The player’s profile object, or null if the request fails Reference: Mojang API - UUID to Profile and Skin/Cape

​
Skin Management

​
changeSkin

Send a skin change request to Mojang. The player must rejoin the server to see the new skin. 
import gg.essential.api.utils.mojang.Model
import java.util.UUID

val accessToken = "player_session_token"
val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val skinUrl = "https://example.com/skin.png"

val response = mojangAPI.changeSkin(
    accessToken = accessToken,
    uuid = uuid,
    model = Model.STEVE,
    url = skinUrl
)

if (response != null) {
    println("Skin changed successfully: ${response.name}")
}
Parameters:
  • accessToken: String - Session token for authentication with Mojang
  • uuid: UUID - Player UUID (must match the session token)
  • model: Model - Skin model type (STEVE or ALEX)
  • url: String - Image URL of the new skin
Returns: SkinResponse? - Response from Mojang, or null if the request fails Reference: Mojang API - Change Skin

​
Data Types

​
Profile

data class Profile(
    val id: String?,           // Player UUID (no dashes)
    val name: String?,         // Player username
    val properties: List<Property>?
) {
    val textures: ProfileTextures  // Decoded skin and cape data
}

​
ProfileTextures

data class ProfileTextures(
    val timestamp: Long?,
    val profileId: String?,
    val profileName: String?,
    val textures: Textures?
)

data class Textures(
    val skin: TextureURL?,
    val cape: TextureURL?
)

data class TextureURL(val url: String?)

​
Model

Skin model enumeration: 
enum class Model(
    val type: String,      // Internal Minecraft name
    val variant: String    // Mojang service name
) {
    STEVE("default", "classic"),
    ALEX("slim", "slim");
    
    companion object {
        fun byType(str: String): Model?
        fun byTypeOrDefault(str: String): Model
        fun byVariant(str: String): Model?
        fun byVariantOrDefault(str: String): Model
    }
}

​
SkinResponse

data class SkinResponse(
    val id: String,
    val name: String,
    val skins: List<Skin>?,
    val capes: List<Skin>
)

data class Skin(
    val id: String,
    val state: String,
    val url: String,
    val variant: String
)

​
Name (Deprecated)

@Deprecated("Name history has been removed from the Mojang API")
data class Name(
    val name: String?,
    val changedToAt: Long?
)

​
Method Reference

interface MojangAPI {
    fun getUUID(name: String): CompletableFuture<UUID>?
    fun getName(uuid: UUID): CompletableFuture<String>?
    fun getProfile(uuid: UUID): Profile?
    fun changeSkin(
        accessToken: String,
        uuid: UUID,
        model: Model,
        url: String
    ): SkinResponse?
    
    @Deprecated("Name history has been removed from the Mojang API")
    fun getNameHistory(uuid: UUID?): List<Name?>?
}

​
Common Use Cases

​
Looking Up Player Information

import gg.essential.api.EssentialAPI

fun lookupPlayer(username: String) {
    val api = EssentialAPI.getMojangAPI()
    
    api.getUUID(username)?.thenAccept { uuid ->
        println("Found UUID: $uuid")
        
        // Now fetch the full profile
        val profile = api.getProfile(uuid)
        if (profile != null) {
            println("Player name: ${profile.name}")
            println("Skin URL: ${profile.textures.textures?.skin?.url}")
        }
    }
}

​
Displaying Player Skins

fun getPlayerSkinUrl(uuid: UUID): String? {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid) ?: return null
    
    return profile.textures.textures?.skin?.url
}

fun getPlayerCapeUrl(uuid: UUID): String? {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid) ?: return null
    
    return profile.textures.textures?.cape?.url
}

​
Async Player Lookup

import gg.essential.api.utils.Multithreading

fun asyncPlayerLookup(username: String, callback: (UUID?) -> Unit) {
    val api = EssentialAPI.getMojangAPI()
    
    Multithreading.runAsync {
        val future = api.getUUID(username)
        future?.thenAccept { uuid ->
            callback(uuid)
        } ?: callback(null)
    }
}

​
Checking Skin Model

import gg.essential.api.utils.mojang.Model

fun getPlayerSkinModel(uuid: UUID): Model {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid)
    
    // Check if player uses slim (Alex) or classic (Steve) model
    val variant = profile?.textures?.textures?.skin?.variant ?: "classic"
    return Model.byVariantOrDefault(variant)
}

​
Notes

  • All network operations return futures or nullable types - always handle failure cases
  • The Mojang API has rate limits - cache responses when possible
  • Name history endpoint has been deprecated by Mojang and is no longer functional
  • Skin changes require valid authentication tokens
  • Players must rejoin servers to see skin changes take effect

Build docs developers (and LLMs) love

Get started for freeTalk to us