Mojang API

Notes

• All public APIs are rate limited so you are expected to cache the results. This is currently set at 600 requests per 10 minutes but this may change.
• For some parts of the API, demo accounts are sometimes included, sometimes not. Mojang keeps changing this.

API Status

 GET https://status.mojang.com/check

Returns status of various Mojang services. Possible values are green (no issues), yellow (some issues), red (service unavailable).

Response

[
  {
    "minecraft.net": "yellow"
  },
  {
    "session.minecraft.net": "green"
  },
  {
    "account.mojang.com": "green"
  },
  {
    "auth.mojang.com": "green"
  },
  {
    "skins.minecraft.net": "green"
  },
  {
    "authserver.mojang.com": "green"
  },
  {
    "sessionserver.mojang.com": "yellow"
  },
  {
    "api.mojang.com": "green"
  },
  {
    "textures.minecraft.net": "red"
  }
]

Username -> UUID at time

 GET https://api.mojang.com/users/profiles/minecraft/<username>?at=<timestamp>

This will return the uuid of the name at the timestamp provided.

?at=0 can be used to get the UUID of the original user of that username, however it only works if the name was changed at least once, or if the account is legacy.

• The timestamp is a UNIX timestamp (without milliseconds)
• When the at parameter is not sent, the current time is used

Response

{
  "id": "7125ba8b1c864508b92bb5c042ccfe2b",
  "name": "KrisJelbring"
}

• name is the current name of that uuid, it is not the name requested!
• legacy only appears when true (not migrated to mojang account)
• demo only appears when true (account unpaid)

If there is no player with the given username an HTTP status code 204 (No Content) is sent without any HTTP body.
If the timestamp is not a number, too big or too small the HTTP status code 400 (Bad Request) is sent with an error message looking like this:

{
  "error": "IllegalArgumentException",
  "errorMessage": "Invalid timestamp."
}

UUID -> Name history

  https://api.mojang.com/user/profiles/<uuid>/names

Returns all the usernames this user has used in the past and the one they are using currently. The UUID must be given without hyphens.

Response

[
  {
    "name": "Gold"
  },
  {
    "name": "Diamond",
    "changedToAt": 1414059749000
  }
]

The changedToAt field is a Java timestamp in milliseconds.

Playernames -> UUIDs

 POST https://api.mojang.com/profiles/minecraft

Where 'minecraft' - agent name

This will return player UUIDS and some extras.

Payload

[
    "maksimkurb",
    "nonExistingPlayer" //Test for non-existing player
]

Response

[
    {
        "id": "0d252b7218b648bfb86c2ae476954d32",
        "name": "maksimkurb",
        "legacy": true,
        "demo": true
    }
]

• name is case-corrected
• legacy only appears when true (profile not migrated to mojang.com)
• demo only appears when true (account unpaid)
• IllegalArgumentException is returned when any of the usernames is null or ""
• The Content-Type HTTP header must be application/json
• You cannot request more than 100 names per request

UUID -> Profile + Skin/Cape

 https://sessionserver.mojang.com/session/minecraft/profile/<uuid>

This will return the player's username plus any additional information about them (e.g. skins). Example: https://sessionserver.mojang.com/session/minecraft/profile/4566e69fc90748ee8d71d7ba5aa00d20

This has a much stricter rate limit: You can request the same profile once per minute, however you can send as many unique requests as you like.

Response

{
    "id": "<profile identifier>",
    "name": "<player name>",
    "properties": [ 
        {
            "name": "textures",
            "value": "<base64 string>",
            "signature": "<base64 string; signed data using Yggdrasil's private key>" // Only provided if ?unsigned=false is appended to url
        }
    ]
}

The "value" base64 string for the "textures" object decoded:

{
    "timestamp": "<java time in ms>",
    "profileId": "<profile uuid>",
    "profileName": "<player name>",
    "isPublic": "<true or false>",
    "textures": {
        "SKIN": {
            "url": "<player skin URL>"
        },
        "CAPE": {
            "url": "<player cape URL>"
        }
    }
}

• The timestamp is sometimes in the past (probably due to cached results?)
• The "SKIN" object will have "metadata": {"model": "slim"} if the player model has slim arms (“Alex?” style). For square arms (“Steve?” style), "metadata" will be missing.
• If no custom skin has been set, "SKIN" will be missing.
  Whether the player has the “Alex?” or “Steve?” skin depends on the Java hashCode of their UUID. Steve is used for even hashes. Example implementations:
  • PHP
  • Go
  • JavaSript (includes explanation)
  • Java (includes sample UUIDs)
• Likewise "CAPE" will be missing if the account has no cape.

Change Skin

  PUT https://api.mojang.com/user/profile/<uuid>/skin

This will set the skin for the selected profile.

Response

Testing needs to be done, I believe an empty payload is returned if successful

Headers

Authorization: Bearer <access token>

Payload

{
    "model":"<alex/steve>"
}

With the file of the skin attached as part of the PUT request.

Examples

Go | uuids or names to profiles with skins, capes and name histories

Python | uuids or names to profiles

Python | names file to uuids+names file

PHP | uuids to names

PHP | uuids to names, names to uuids

JavaScript | uuids or names to profiles with skins, capes and name histories