Getting Started

A tutorial in how to use the API

Alpha

This API is still under development and the layouts of the responses might change several times until the final release. All users during alpha should know that the API might be unavailable at any point in time and structurally change spontaneously.

Authentication

Certain requests will require you to provide a valid bearer token linked to your Minecraft account. For now, these tokens can only be generated by requesting so on the Discord by opening a support ticket after being verified.

By requesting a page with authentication you need to add your bearer token to the header. In Java when using a HttpsURLConnection this would look like the following:

HttpsURLConnection connection = (HttpsURLConnection) new URL(url).openConnection();
connection.addRequestProperty("Content-type", "application/json");
connection.addRequestProperty("Authorization", "Bearer " + TOKEN);

API endpoints that need no token can of course be requested without adding the bearer token.

ToS

• Do not abuse our API.

• Do not use the API to get access to hidden information. This implies that it is forbidden to use the API to find nicked players!

• Do not share your bearer token. You vouch for it.

• Do not use alt accounts in order to get higher rate limits.

Abuse

Do not abuse our API in any way. This also includes not using our API for getting UUID by player name and vice versa. Use the official Mojang API for that. We are free to revoke your access to our API at any time if we think you are abusing our system.

Rate limit

The rate limit is not a fixed value and can be changed on request with a valid reason.

Default

The default rate limit is 60 requests in 60 seconds.

Cost

By default, requests will cost 1 rate request. If an API request costs more or less there will be a warning below the corresponding API method documentation.

Status

Your current rate limits and user info will be written into the response headers.

Header	Description	Example
X-User-UUID	Your minecraft UUID	531bf4b9-c79d-4eed-9252-ee60acfe524a
X-User-Rank	Your API rank	USER
X-RateLimit-Limit	Your API limit	120
X-RateLimit-Milliseconds	Your API limit time interval	60000
X-RateLimit-Rate-Current	Your current request rate	42

You can also view your current rate by calling the main page with your token as a parameter. This action won't increase your rate.

Main page & API info

get

This is the main page of the API with a welcome/info message. If you provide your token, you can see your UUID, rank, rate-limit, rate-limit-time and your current rate.

Authorizations

Query parameters

tokenstringOptional

deprecated

Responses

get

HTTPcURLJavaScriptPython

GET /api/v1/ HTTP/1.1
Host: mcplayhd.net
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "status": 1,
  "path": "text",
  "timeStamp": "text",
  "processingTime": 1,
  "data": {
    "message": "text",
    "authenticated": true,
    "user": {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "rank": "USER",
      "rateLimit": 1,
      "rateLimitTimeMs": 1,
      "currentRate": 1
    }
  }
}

This action costs 0 rate requests.

Endpoints

You can find a list of all publicly accessible endpoints (when you have a token, that is) in this documentation.

If you prefer swagger you are free to have a look around at https://mcplayhd.net/api/v1/swagger-ui/index.html. You can test the endpoints and even provide your authentication token.