# AlloyMC developer docs

The AlloyMC API gives you the same data the AlloyMC website shows: public profiles, who follows whom, Minecraft accounts people linked, and the newest Alloy release. It's a plain JSON API over HTTPS at:

```
https://api.alloymc.dev/v1
```

## What you can build today

- **Profile cards and badges** on your own site, with someone's avatar, name and follower count.
- **Discord bots** that show an AlloyMC profile when someone types a handle.
- **Server websites and plugins** that show which players have an AlloyMC profile, from their Minecraft UUID.
- **Update checks** for tools that want to know the newest Alloy version.

There are short, copyable examples for each in [Recipes](https://api.alloymc.dev/docs/recipes).

## How it works

- **Public reads need no key.** Anything visible on alloymc.dev without signing in can be read without a token: profiles, follower lists, avatars, linked Minecraft accounts.
- **Writes need a bearer token.** Changing a profile or following someone happens on behalf of a signed-in person. Today only Alloy can get such tokens; apps of your own are [next on the roadmap](https://api.alloymc.dev/docs/roadmap).
- **Browsers welcome.** CORS is open to every origin, so you can call the API straight from a web page.
- **Stable.** Everything lives under `/v1`. Within a version we only add things; nothing is renamed or removed. Changes are listed in the [changelog](https://api.alloymc.dev/docs/changelog).

## Where to go next

1. [Quickstart](https://api.alloymc.dev/docs/quickstart): your first request in a minute.
2. [Conventions](https://api.alloymc.dev/docs/conventions): errors, limits, pages of results.
3. [API reference](https://api.alloymc.dev/docs/reference): every endpoint with an example. The same thing as an [OpenAPI 3.1 file](https://api.alloymc.dev/v1/openapi.json).

## Help and rules

Questions, ideas or a bug: [open an issue on GitHub](https://github.com/Elchi-dev/AlloyMC/issues) or write to [contact@elchi.dev](mailto:contact@elchi.dev). Using the API means agreeing to the [terms of use](https://legal.alloymc.dev/terms#the-api), which come down to: respect rate limits, respect people's choices (deleted means deleted), and don't pretend to be AlloyMC.