Using the API

Send your key in the Authorization header. Every request is for one server, and only works with that server's keys while Bloxly is in it.

A server's keys share a limit of 10 requests every 10 seconds, with no daily limit. Each answer says how many are left in its RateLimit-Remaining header and how many seconds until another is free in RateLimit-Reset. Past the limit you get 429 RATE_LIMITED: wait the seconds in its Retry-After header before trying again.

Members are only returned when they let people in their servers look them up, in their Bloxly settings. Everyone else answers 404 NOT_FOUND, the same as a member who isn't verified, so a private member can't be told apart from an unverified one.

Base URL: https://bloxly.bot/api/v1

Endpoints

Open one to see a request in cURL, JavaScript or Python, and what it answers. Every request counts towards your server's limit.

GETDiscord to Roblox/guilds/{serverId}/discord-to-roblox/{discordId}

Finds the Roblox account a member uses in your server: the one they picked for it, or else their default.

curl "https://bloxly.bot/api/v1/guilds/{serverId}/discord-to-roblox/{discordId}" \
-H "Authorization: $BLOXLY_API_KEY"
Response, 200 OK
{
"discordId": "592185176033984542",
"robloxId": "156"
}
GETRoblox to Discord/guilds/{serverId}/roblox-to-discord/{robloxId}

Lists the members of your server who use a Roblox account there. Most accounts have one, but someone can link the same Roblox account to more than one Discord account.

curl "https://bloxly.bot/api/v1/guilds/{serverId}/roblox-to-discord/{robloxId}" \
-H "Authorization: $BLOXLY_API_KEY"
Response, 200 OK
{
"robloxId": "156",
"discordIds": ["592185176033984542"]
}
POSTUpdate a member/guilds/{serverId}/members/{discordId}/update

Updates a member's roles and nickname in your server, the same as /update. Use it after something changes on Roblox, such as a rank change from your ranking bot. Bloxly answers straight away and updates them within a few seconds, and your verification log shows the result when anything changed.

curl -X POST "https://bloxly.bot/api/v1/guilds/{serverId}/members/{discordId}/update" \
-H "Authorization: $BLOXLY_API_KEY"
Response, 202 Accepted
{
"discordId": "592185176033984542",
"status": "queued"
}

Errors

Failed requests answer with a status and a JSON body of { "message", "error" }.

400BAD_REQUEST
An id in the path isn't a Discord or Roblox user id.
401UNAUTHORIZED
No key was sent, or the key was deleted.
403WRONG_SERVER
The key belongs to a different server than the one in the path.
404NOT_MEMBER
That Discord user isn't in your server.
404NOT_FOUND
No Roblox account to share: the member isn't verified, or keeps their account private.
404SERVER_NOT_FOUND
Bloxly isn't in your server anymore.
429RATE_LIMITED
Your server's keys made 10 requests in the last 10 seconds. Wait the seconds in the Retry-After header.
429TOO_MANY_FAILURES
Too many requests with a missing or wrong key came from your address. Wait the seconds in the Retry-After header.
503BUSY
Bloxly is answering a lot of lookups right now. Wait the seconds in the Retry-After header and try again.
503DISCORD_UNAVAILABLE
Discord couldn't confirm who is in your server. Try again shortly.

API terms

By creating a key, you agree to these terms on top of Bloxly's Terms of Service.

  1. Keep keys secret. Store them in an environment variable or secret manager, never in source code or chat. Give each person on your team their own key instead of sharing one, and delete a key straight away if it leaks.
  2. Only use the API for your own server.
  3. Only look someone up because of something they did in your server or app, such as joining, running a command or being ranked. Don't work through lists of ids to collect accounts.
  4. Keep what the API returns for at most 30 days. After that, look it up again or delete it, and delete it if Bloxly no longer returns it. Anything you already knew before asking, such as a Roblox id from your own game, isn't covered by this.
  5. Delete what you got from the API about someone when they ask you to, including when Bloxly passes their request on to you.
  6. Don't sell, share or publish the accounts it returns, pass them on through your own API or dataset, or use them to track people outside your server. Roblox's policies forbid it, and so does Bloxly.
  7. Stay within the rate limit. When you get 429, stop and wait the seconds in its Retry-After header before sending more.
  8. If you only need to know who someone is on Roblox inside your own app, use Roblox's OAuth sign-in instead, so they agree to it directly.
  9. Bloxly can delete keys that break these terms, or that make far more requests than a server needs.