API Docs

Integrate Link-Craft account links into your Minecraft plugin or Discord bot.

Overview

The Link-Craft REST API lets server owners query the account links their players have created. You can look up which Minecraft account is connected to a Discord user, and vice versa.

All API requests are authenticated with your server's API key, which you can generate or regenerate from your server admin dashboard.

The API only returns data for your server. You cannot access data from other servers - each API key is scoped to a single tenant.

Authentication

Include your API key in every request as a Bearer token in the Authorization header:

Authorization: Bearer lc_yourApiKeyHere

You can find and regenerate your API key in the API Key section of your server admin dashboard.

Base URL

https://api.link-craft.com/v1

All endpoints are relative to this base URL. All responses are JSON.

Errors

Errors return a JSON body with an error field explaining what went wrong.

Status	Meaning
`200`	Success
`400`	Bad request - missing or invalid parameter
`401`	Missing or invalid API key
`404`	Link not found
`429`	Rate limit exceeded
`500`	Server error

GET link by Discord ID

Returns the account link for a specific Discord user on your server.

GET /v1/links/{discord_id}

Path parameters

Parameter	Type	Description
`discord_id` required	string	The Discord user's snowflake ID (e.g. `123456789012345678`)

Response

{
  "discord_id":   "123456789012345678",
  "mc_uuid":      "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "mc_username":  "Notch",
  "linked_at":    "2025-04-15T12:34:56.000Z"
}

Example (curl)

curl https://api.link-craft.com/v1/links/123456789012345678 \
  -H "Authorization: Bearer lc_yourApiKeyHere"

Example (Java/Bukkit)

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.link-craft.com/v1/links/" + discordId))
    .header("Authorization", "Bearer " + API_KEY)
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

// Parse JSON with your favourite library
JSONObject link = new JSONObject(response.body());
String mcUuid = link.getString("mc_uuid");

GET link by Minecraft UUID

Returns the account link for a specific Minecraft player on your server.

GET /v1/links/mc/{mc_uuid}

Path parameters

Parameter	Type	Description
`mc_uuid` required	string	The Minecraft player's UUID with dashes (e.g. `069a79f4-44e9-4726-a5be-fca90e38aaf5`)

Response

{
  "discord_id":   "123456789012345678",
  "mc_uuid":      "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "mc_username":  "Notch",
  "linked_at":    "2025-04-15T12:34:56.000Z"
}

GET all links

Returns a paginated list of all account links on your server. Use this to do a full sync or bulk export.

GET /v1/links

Query parameters

Parameter	Type	Default	Description
`page` optional	number	1	Page number (1-based)
`limit` optional	number	50	Results per page, max 500

Response

{
  "links": [
    {
      "discord_id":  "123456789012345678",
      "mc_uuid":     "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "mc_username": "Notch",
      "linked_at":   "2025-04-15T12:34:56.000Z"
    }
  ],
  "total": 42,
  "page":  1,
  "limit": 50
}

Security model

The API is designed so that each server can only access its own data:

Your API key is matched to your server's tenant record in our database.
All queries are automatically scoped to your server - there is no way to read another server's data with your key.
API keys are stored hashed and can be regenerated at any time from the admin dashboard.
All traffic is encrypted via TLS.

Keep your API key secret. Anyone with your key can read all account links for your server. If you believe your key has been compromised, regenerate it immediately from the admin dashboard.

Rate limits

The API is rate-limited to 200 requests per 15 minutes per IP address. If you exceed this, you will receive a 429 Too Many Requests response.

For bulk operations, use the paginated GET /v1/links endpoint rather than making individual requests per player.