GuildLB Logo

GuildLB

For Developers

GuildLB API

Read-only access to the guild and player leaderboard data that powers GuildLB, for your own tools, bots and dashboards.

View the raw OpenAPI 3.1 spec (/api/openapi.json)
1. Authentication

Authentication

Read-only access to GuildLB's guild and player leaderboard data. Send your key with every request using either header:

  • Authorization: Bearer YOUR_API_KEY
  • x-api-key: YOUR_API_KEY

A missing or invalid key returns 401 UNAUTHORIZED. Keep your key secret - never put it in client-side code or a public repository. Usage terms follow our Terms of Service.

2. Endpoints

Available endpoints

Every response returns the same envelope: a success boolean, a data payload on success, and an error object on failure. Generated from the OpenAPI spec.

Endpoints

Guilds

Guild lookups.

GET/api/guild/{name}

Get a guild by name

Returns stored guild data. It is never refreshed from Hypixel on request and may be up to a few days old.

Auth API key via Bearer token or x-api-key header

Parameters

  • name * (path · string)Guild name.

Responses

  • 200 The guild, with its SkyBlock leaderboard metrics. Abridged; more fields are returned (per-category metric maps, members with more fields, and others).
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "id": "0123456789abcdef0123456789abcdef",
    "name": "Example Guild",
    "level": 120,
    "skillavg": 52.4,
    "slayers": 1850000,
    "catacombs": 48.3,
    "networth": 41200000000,
    "networth_formatted": "41.20B",
    "slayers_formatted": "1.85M",
    "placement": 12,
    "is_alliance": false,
    "top_skill": null,
    "top_rank": null,
    "discord_link": "https://discord.gg/example",
    "discordUrl": "https://discord.gg/example",
    "iconUrl": "https://guildlb.com/api/guild/Example%20Guild/icon",
    "bannerUrl": null,
    "bannerPos": null,
    "bio": "An example guild.",
    "preferred_games": [],
    "memberCount": 2,
    "scammer_source": "SkyBlockZ",
    "members": [
      {
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "ExamplePlayer",
        "guild_id": "0123456789abcdef0123456789abcdef",
        "guild_name": "Example Guild",
        "guild_rank": "Guild Master",
        "skyblock_level": 312,
        "skills": 54.1,
        "slayers": 950000,
        "catacombs": 51.2,
        "networth": 2300000000,
        "scammer_status": "clear"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 404 No matching resource.
    Show example for 404 response example
    {
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
Endpoints

Players

Player lookups.

GET/api/player/{name}

Get a player by name

Returns the stored player record. Data is stored, never refreshed from Hypixel on request, and may be up to a few days old. Networth here is the stored value from the last tracked update. An untracked player returns 404 PLAYER_NOT_TRACKED and is not queued.

Auth API key via Bearer token or x-api-key header

Parameters

  • name * (path · string)Minecraft username (1-16 letters, digits or underscores) or UUID.

Responses

  • 200 The player, with skills, slayers, dungeons, stored networth and related metrics. Abridged; more fields are returned (per-category metric maps and breakdowns).
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "ExamplePlayer",
    "guild_id": "0123456789abcdef0123456789abcdef",
    "guild_name": "Example Guild",
    "guild_rank": "Guild Master",
    "skyblock_level": 312,
    "skills": 54.1,
    "slayers": 950000,
    "catacombs": 51.2,
    "networth": 2300000000,
    "non_cosmetic_networth": 2100000000,
    "networth_formatted": "2.30B",
    "slayers_formatted": "950.00K",
    "updated_at": "2026-10-05T11:30:00Z",
    "socials": {},
    "scammer_status": "clear",
    "scammer_alt": false,
    "scammer_reason": null,
    "scammer_source": "SkyBlockZ",
    "scammer_flags": []
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
  • 400 VALIDATION_ERROR: the name is not a valid Minecraft username or UUID.
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 404 PLAYER_NOT_TRACKED: the player is not tracked yet. error.details.queued is always false.
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
Endpoints

Player assets

Player networth.

GET/api/player/{name}/networth

Get a player's networth

Stored networth (total and non-cosmetic) from the player's last tracked update; it may be up to a few days old and is never refreshed on request. Breakdown is not available. An untracked player is queued for tracking (at most 30 queue insertions per API key per hour, and a name is re-queued at most once per 10 minutes) and answered with 404 PLAYER_NOT_TRACKED. Retry later.

Auth API key via Bearer token or x-api-key header

Parameters

  • name * (path · string)Minecraft username (1-16 letters, digits or underscores) or UUID.

Responses

  • 200 Stored networth: total, nonCosmetic, updatedAt and breakdown (always null).
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "total": 2300000000,
    "nonCosmetic": 2100000000,
    "updatedAt": "2026-10-05T11:30:00Z",
    "breakdown": null
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
  • 400 VALIDATION_ERROR: the name is not a valid Minecraft username or UUID.
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 404 PLAYER_NOT_TRACKED: the player is not tracked yet. error.details.queued is true when the player is now queued for tracking, false when the queue request was throttled or unavailable. Retry later.
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
Endpoints

Guild blacklist

Alliance guild blacklists. Requires a guild-scoped API key.

GET/api/alliance/blacklist/check/{player}

Check a player against the alliance blacklist

Is this player blacklisted by any alliance guild? The path value may be a UUID or a username. Requires a guild-scoped API key.

Auth API key via Bearer token or x-api-key header

Parameters

  • player * (path · string)Player UUID or username.

Responses

  • 200 Whether the player is blacklisted, and the matching entries.
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "blacklisted": true,
    "entries": [
      {
        "guildId": "0123456789abcdef0123456789abcdef",
        "guildName": "Example Guild",
        "category": "SCAMMING",
        "reason": "Chargeback scam",
        "addedBy": "123456789012345678",
        "createdAt": "2026-08-08T12:00:00Z"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
GET/api/alliance/scammer/{player}

Check if a player is a known scammer

Combines SkyBlockZ with every alliance guild's public Scamming blacklist entries. The path value may be a UUID or a username. SkyBlockZ is refreshed live when our stored result is stale, so a call can take a few seconds. Requires a guild-scoped API key.

Auth API key via Bearer token or x-api-key header

Parameters

  • player * (path · string)Player UUID or username.

Responses

  • 200 scammer is true when any source flags the player. skyblockz_status is flagged, clear, or unknown (SkyBlockZ unreachable). flags lists each hit with its source (SkyBlockZ or Guild Alliance).
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "uuid": "0123456789abcdef0123456789abcdef",
    "name": "ExamplePlayer",
    "scammer": true,
    "skyblockz_status": "flagged",
    "flags": [
      {
        "source": "SkyBlockZ",
        "reason": "Coop scam"
      },
      {
        "source": "Guild Alliance",
        "reason": "Chargeback scam"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
  • 400 A required field was missing or malformed.
    Show example for 400 response example
    {
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Please fill in the required fields."
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 404 No Minecraft account has that username or UUID.
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
  • 502 The lookup failed upstream. Retry later.
GET/api/guild/blacklist

Get your guild's blacklist

The calling guild's own blacklist. Requires a guild-scoped API key.

Auth API key via Bearer token or x-api-key header

Responses

  • 200 The calling guild's blacklist entries.
    Show example for 200 response example
    {
  "success": true,
  "data": [
    {
      "playerUuid": "0123456789abcdef0123456789abcdef",
      "category": "SCAMMING",
      "reason": "Chargeback scam",
      "addedBy": "123456789012345678",
      "public": true,
      "createdAt": "2026-08-08T12:00:00Z"
    }
  ],
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
POST/api/guild/blacklist

Add a player to your guild blacklist

Add one entry to the calling guild's blacklist. Only alliance guilds may write. If the player is already on this guild's list, returns 409 with the existing reason (remove them first to change it). Entries are keyed by player UUID, so an entry follows the player across guild changes and shows in the combined alliance blacklist. Requires a guild-scoped API key.

Auth API key via Bearer token or x-api-key header

Request body

Show example for request body
{
  "playerUuid": "0123456789abcdef0123456789abcdef",
  "category": "SCAMMING",
  "reason": "Chargeback scam",
  "addedBy": "123456789012345678",
  "public": true
}

Responses

  • 200 The stored entry: id, playerUuid, category and public.
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "id": 42,
    "playerUuid": "0123456789abcdef0123456789abcdef",
    "category": "SCAMMING",
    "public": true
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
  • 400 A required field was missing or malformed.
    Show example for 400 response example
    {
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Please fill in the required fields."
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 403 The calling guild is not an alliance guild.
  • 409 The player is already on this guild's blacklist; the message includes the existing reason.
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
DELETE/api/guild/blacklist/{player}

Remove a player from your guild blacklist

Remove one player (by UUID) from the calling guild's own blacklist. Requires a guild-scoped API key.

Auth API key via Bearer token or x-api-key header

Parameters

  • player * (path · string)Player UUID to remove.

Responses

  • 200 The player was removed.
    Show example for 200 response example
    {
  "success": true,
  "data": {
    "removed": true
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
  • 401 Missing or invalid API key.
    Show example for 401 response example
    {
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
  • 404 No matching resource.
    Show example for 404 response example
    {
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
  • 429 Too many requests. Honor the Retry-After header when present.
    Show example for 429 response example
    {
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
3. Rate limits

Rate limits & fair use

  • Cache responses rather than polling faster than the data changes.
  • Use pagination (limit/offset) instead of scraping the full dataset.
  • Back off on 429 RATE_LIMITED, honoring the Retry-After header.
4. Apply for access

Request an API key

Keys are issued by hand. Tell us what you are building and we will reach out.