Machine APIv1
Look up any Discord user.
This endpoint is for server-to-server calls from another webapp. It returns a global Discord profile by ID, and adds staff-guild membership and staff status when the user is in that guild.
POST
https://royaleapi-admin.pages.dev/api/users/lookup Authenticate with an Authorization: Bearer <token> header. The token is a server-side secret shared with the calling application. Do not send it from a public browser client.
Request
Terminal
curl --request POST 'https://royaleapi-admin.pages.dev/api/users/lookup' \
--header 'Authorization: Bearer $LOOKUP_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"discordId":"123456789012345678"}'Body
{
"discordId": "123456789012345678",
"includeRoles": false
}Fields
- discordId
- Required. A 17–20 digit Discord snowflake.
- includeRoles
- Optional boolean. Adds raw role IDs when the user is in the configured guild.
200 response
{
"found": true,
"user": {
"id": "123456789012345678",
"username": "someuser",
"globalName": "Some User",
"discriminator": "0",
"displayName": "Some User",
"avatarUrl": "https://cdn.discordapp.com/avatars/123456789012345678/abc123.png?size=256",
"bannerUrl": null,
"bot": false,
"system": false,
"createdAt": "2015-12-07T16:13:12.216Z"
},
"guild": {
"id": "987654321098765432",
"name": "Example Community",
"isMember": true,
"isStaff": true,
"nickname": "Some Nickname",
"joinedAt": "2024-01-14T18:22:10.000000+00:00"
},
"isStaff": true,
"checkedAt": "2026-01-01T12:00:00.000Z"
}isStaff is computed at request time from the guild member's current roles. If the user is not in the configured guild, the request still succeeds with guild: null and isStaff: false. Discord's bot API returns public profile data only, not email or private account details.
Errors
StatusCodeMeaning
401UNAUTHORIZEDUNAUTHORIZED The bearer token is missing or invalid.
400INVALID_REQUESTINVALID_REQUEST The JSON body or Discord ID is invalid.
404USER_NOT_FOUNDUSER_NOT_FOUND No Discord user exists with that ID.
502DISCORD_UNAVAILABLEDISCORD_UNAVAILABLE Discord could not be reached or rejected the bot token.
503API_NOT_CONFIGUREDAPI_NOT_CONFIGURED The server is missing its API or bot configuration.
{
"statusCode": 404,
"statusMessage": "Not Found",
"data": {
"error": {
"code": "USER_NOT_FOUND",
"message": "No Discord user exists with that ID."
}
}
}