> For the complete documentation index, see [llms.txt](https://api.mcplayhd.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.mcplayhd.net/information/getting-started.md).

# 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](https://mcplayhd.net/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:

```java
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](https://api.mojang.com/) 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**](/information/getting-started.md#main-page-and-api-info) with your token as a parameter.\
This action won't increase your rate.

{% openapi src="/files/qiyEEbtdN7ZpfSwQXeMu" path="/" method="get" %}
[api-docs.json](https://474620403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYEHEr7ewmv4cz4gXwv%2Fuploads%2FSrpCGsmdhp9ix6WXPhLt%2Fapi-docs.json?alt=media\&token=ba34de80-55ee-42dc-b605-cd157630b6a5)
{% endopenapi %}

{% hint style="warning" %}
This action costs **0** rate requests.
{% endhint %}

## 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.