Difference between revisions of "Mojang API"

From wiki.vg
Jump to navigation Jump to search
(lots of stuff, more details)
Line 3: Line 3:
  
 
All public APIs are rate limited so you are expected to cache the results. This is currently set at 600 per 10 minutes but this may change
 
All public APIs are rate limited so you are expected to cache the results. This is currently set at 600 per 10 minutes but this may change
 +
For some parts of the API, demo account are sometimes included, sometimes not. Mojang keeps changing this.
  
−
== Username -> UUID ==
+
== Username -> Profile at time ==
  
−
   https://api.mojang.com/users/profiles/minecraft/<username>
+
   GET https://api.mojang.com/users/profiles/minecraft/<username>?at=<timestamp>
  
−
This will return the player's current username and uuid
+
This will return the uuid of the name at the timestamp provided.
 +
* The timestamp is a unix timestamp
 +
* When the <code>at</code> parameter is not sent, the current time is used
  
 
=== Response ===
 
=== Response ===
Line 18: Line 21:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Username -> UUID at time ==
+
* <code>name</code> is case-corrected
 +
* <code>legacy</code> only appears when true (not migrated to mojang account)
 +
* <code>demo</code> only appears when true (account unpaid)
  
−
  https://api.mojang.com/users/profiles/minecraft/<username>?at=<timestamp>
 
  
−
This will return the player's username that they had at the timestamp provided and their uuid.
+
== UUID -> Name history ==
−
The timestamp is a unix timestamp
 
−
 
 
−
=== Response ===
 
−
<syntaxhighlight lang="javascript">
 
−
{
 
−
  "id": "7125ba8b1c864508b92bb5c042ccfe2b",
 
−
  "name": "KrisJelbring"
 
−
}
 
−
</syntaxhighlight>
 
−
 
 
−
== UUID -> All current/previous names ==
 
  
 
   https://api.mojang.com/user/profiles/<uuid>/names
 
   https://api.mojang.com/user/profiles/<uuid>/names
Line 46: Line 39:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Players profiles by names ==
+
 
 +
 
 +
== Playernames -> UUIDs ==
  
 
   https://api.mojang.com/profiles/minecraft
 
   https://api.mojang.com/profiles/minecraft
Line 52: Line 47:
 
Where 'minecraft' - agent name
 
Where 'minecraft' - agent name
  
−
This will return players profiles.
+
This will return player UUIDS and some extras.
  
 
=== Payload ===
 
=== Payload ===
Line 68: Line 63:
 
[
 
[
 
     {
 
     {
−
         "id": "0d252b7218b648bfb86c2ae476954d32",   //Profile uuid
+
         "id": "0d252b7218b648bfb86c2ae476954d32",
−
         "name": "maksimkurb",                       //Profile nickname
+
         "name": "maksimkurb",
−
         "legacy": true,                             //Profile not migrated to mojang.com?  (Only appears, when true)
+
         "legacy": true,
−
         "demo": true                                 //Game wasn't bought                  (Only appears, when true)
+
         "demo": true
 
     }
 
     }
−
    // This will return only information about real (existing) profiles.
 
 
]
 
]
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Player Public Skin Information ==
+
* 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 <code>Content-Type</code> HTTP header must be <code>application/json</code>
 +
* You cannot request more than 100 names per request
 +
 
 +
 
 +
 
 +
== uuid -> Profile + Skin/Cape ==
  
 
   https://sessionserver.mojang.com/session/minecraft/profile/<uuid>
 
   https://sessionserver.mojang.com/session/minecraft/profile/<uuid>
Line 83: Line 86:
 
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 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, once a minute per a uuid
+
This has a much stricter rate limit: You can request the same profile once per minute.
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
Line 91: Line 94:
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
−
     "id":"profile identifier",
+
     "id": "<profile identifier>",
−
     "name":"player name",
+
     "name": "<player name>",
−
     "properties":[  
+
     "properties": [  
−
{
+
        {
−
    "name":"textures",
+
            "name": "textures",
−
    "value":"base64 string",
+
            "value": "<base64 string>",
−
    "signature":"base64 string; signed data using Yggdrasil's private key" // Only provided if ?unsigned=false is appended to url
+
            "signature": "<base64 string; signed data using Yggdrasil's private key>" // Only provided if ?unsigned=false is appended to url
−
}
+
        }
 
     ]
 
     ]
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
"value" base64 string decoded:
+
The "value" base64 string for the "textures" object decoded:
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
−
     "timestamp":"some numbers",
+
     "timestamp": "<unix time in ms>",
−
     "profileId":"profile identifier",
+
     "profileId": "<profile uuid>",
−
     "profileName":"player name",
+
     "profileName": "<player name>",
−
     "isPublic":"true or false",
+
     "isPublic": "<true or false>",
−
     "textures":{
+
     "textures": {
−
"SKIN":{
+
        "SKIN": {
−
    "url":"player skin URL"
+
            "url": "<player skin URL>"
−
         }
+
         },
−
         "CAPE":{
+
         "CAPE": {
−
    "url":"player cape URL"
+
            "url": "<player cape URL>"
 
         }
 
         }
 
     }
 
     }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
* timestamp sometimes in the past (probably due to cached results?)
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 00:20, 27 July 2014

Notes

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

Username -> Profile 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.

  • The timestamp is a unix timestamp
  • When the at parameter is not sent, the current time is used

Response

{
  "id": "7125ba8b1c864508b92bb5c042ccfe2b",
  "name": "KrisJelbring"
}
  • name is case-corrected
  • legacy only appears when true (not migrated to mojang account)
  • demo only appears when true (account unpaid)


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

Response

[
  "KrisJelbring"
]


Playernames -> UUIDs

 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.

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": "<unix time in ms>",
    "profileId": "<profile uuid>",
    "profileName": "<player name>",
    "isPublic": "<true or false>",
    "textures": {
        "SKIN": {
            "url": "<player skin URL>"
        },
        "CAPE": {
            "url": "<player cape URL>"
        }
    }
}
  • timestamp sometimes in the past (probably due to cached results?)
Retrieved from "https://wiki.vg/index.php?title=Mojang_API&oldid=5948"