Endpoints
Requests, responses, scopes, and errors of each endpoint of the RemiliaNET public API under /api/v1.
Each path starts with https://www.remilia.net/api/v1, and each response is
JSON. Each endpoint lists its scope and its token kind: none, an
app-only token, or a user-delegated token. A
scoped request sends Authorization: Bearer <access_token>. Website endpoints
outside /api/v1 are listed in
Public data without an application.
Every endpoint except the two profile reads wraps its success payload in a
data envelope:
Errors use the error envelope on every endpoint. Each endpoint has an
Example JSON response section with a sample response. The examples use
Remilia Jackson unless a label says otherwise. Other account and friend
identities are anonymized, and empty fields appear as returned. Relative image
paths resolve against https://www.remilia.net, not against the origin of your
app.
Profiles
Both calls return the same profile structure. The token's user identity determines which fields contain data.
For more information about the presentation of the name, the handle, the preferred color, and the profile picture (PFP), see Remilia profiles in your app.
Displayed friends and trophies
user.friendsDisplayed is the user's pinned display list, in the order they
chose. It is not a ranking of their closest or most active friends.
user.trophyShelves describes three shelves of five slots. Indexes 0 to 4 are
the first shelf, 5 to 9 the second, and 10 to 14 the third. A zero marks an empty
slot. Preserve the positions and gaps when you render it. Use
user.allTrophies for trophy details.
Get a profile by handle
GET /users/{username}Returns the public profile of any user, by {username}. The handle picks the
profile. The token, if any, picks the viewer.
Scope: none. No token required.
The comparison is always between the logged-in user and {username}. The
endpoint cannot compare two other users. The profile of another user never
includes their property, statistics, or aggregate scores, even with a user
token.
The server validates a token even on this public endpoint. An expired or
malformed token returns 401 invalid_token.
curl https://www.remilia.net/api/v1/users/remilia_jacksonThe profile object is returned directly (no data wrapper).
Example JSON response: without a token
Remilia Jackson's public profile. Friend names, IDs, and avatars are anonymized.
Example JSON response: with a user token
The same profile viewed by another logged-in user. Mutual friends and achievement details are populated. Friend names, IDs, and avatars are anonymized.
Without a user token, achievementContext, mutualFriends, and
twitterMutuals are empty and owner statistics are null. A user token adds
viewer-specific details. Your own profile includes
owner statistics. twitterMutuals can still be empty for a logged-in viewer.
An unknown username returns 404 with the error envelope:
Get your own profile
GET /meReturns the profile of the account that authorized your application.
isOwnProfile is true. user.property, user.stats, and
user.aggregateScores are null, as on every profile response. The
remaining profile fields use the same structure. Account statistics are
available through GET /me/stats, which
requires the remilia:stats.read scope.
Calling GET /users/{username} with your own username
and your own user token returns the same response. /me needs no username.
Scope: none. Requires a user's token. openid is sufficient.
curl https://www.remilia.net/api/v1/me \
-H "Authorization: Bearer $ACCESS_TOKEN"The response returns the profile object directly, without a data wrapper.
An app-only token returns 403 requires_user.
Example JSON response
Remilia Jackson's own profile. Each achievementContext key is an
achievement ID. viewerOwns indicates whether the viewer owns it. Friend
names, IDs, and avatars are anonymized.
Account connections example
An account with linked services can have populated user.connections.
This shows the connection field from another account's /me response.
Linked usernames and external account IDs are anonymized.
Shared profile fields
Get your account statistics
GET /me/statsReturns per-platform statistics and aggregate scores for the token's user.
Scope: remilia:stats.read · user-delegated token required
curl https://www.remilia.net/api/v1/me/stats \
-H "Authorization: Bearer $ACCESS_TOKEN"Example JSON response: Remilia Jackson
All platforms and aggregate scores are included, even when they are zero. The response has no wallet, token, or collection data.
Notifications
List your notifications
GET /me/notificationsScope: remilia:notifications.read · user-delegated token required
curl "https://www.remilia.net/api/v1/me/notifications?limit=3&page=1" \
-H "Authorization: Bearer $ACCESS_TOKEN"Example JSON response
count, from, guild_name, and message appear only on notification types
that carry them.
Beetle
Get your Beetle state
GET /me/beetleReturns your Beetle game state in data: experience points (XP), level, inventory, hammer durability, and cooldowns.
Scope: remilia:beetle.read · user-delegated token required
The example shows Remilia Jackson's Beetle state after catching a beetle.
Example JSON response
Inventory keys are item codenames. Cooldown values are milliseconds remaining. The response can omit a cooldown with no time remaining.
Optional Beetle fields
Illustrative values for fields omitted when no hammer, streak risk, or active
cooldown is present. These fields belong inside data alongside the fields
in the response above.
List your discovered Beetle cards
GET /me/beetle/cardsReturns the caller's discovered cards keyed by card codename, wrapped in
data. The example shows three entries from Remilia Jackson's collection.
Scope: remilia:beetle.read · user-delegated token required
Example JSON response
The object is keyed by discovered card codename. A user with no discovered
cards receives an empty data object.
Get your Beetle cooldowns
GET /me/beetle/cooldownsReturns the time left before each Beetle action is available again, in
milliseconds, wrapped in data. The response has no inventory or other game
state.
Scope: remilia:beetle.read · user-delegated token required
curl https://www.remilia.net/api/v1/me/beetle/cooldowns \
-H "Authorization: Bearer $ACCESS_TOKEN"A field is absent when its action is available now. When every action is
available, data is an empty object.
Example JSON response
Illustrative response, with catch and hunt on cooldown:
Pokes
Poke a user
POST /users/{handle}/pokeSends a poke to {handle}, attributed to the authenticated user.
Scope: remilia:pokes.write · user-delegated token required
curl -X POST https://www.remilia.net/api/v1/users/remilia_jackson/poke \
-H "Authorization: Bearer $ACCESS_TOKEN"A successful response returns data.target_handle and data.poked_at (a
Unix timestamp in milliseconds). A user cannot poke their own account. The
example pokes Remilia Jackson with the token of another user.
A second poke to the same user within 24 hours returns 429 poke_cooldown. The
error includes next_allowed_at, the next time that user can send a poke.
Example JSON response
Illustrative successful poke:
Cooldown error
Illustrative repeat poke:
Get the poke cooldown
GET /users/{handle}/poke/cooldownReturns whether the authenticated user can poke {handle} now, wrapped in
data. Check it before you show a poke control.
Scope: remilia:pokes.write · user-delegated token required
curl https://www.remilia.net/api/v1/users/remilia_jackson/poke/cooldown \
-H "Authorization: Bearer $ACCESS_TOKEN"An unknown handle returns 404 user_not_found.
Example JSON response
Illustrative response, on cooldown:
Friends
List mutual friends
GET /users/{username}/mutual-friendsReturns the friends that the authenticated user and {username} have in
common, wrapped in data. count is the total. mutuals holds up to five of
them, as public directory identities.
Scope: remilia:social.read · user-delegated token required
curl https://www.remilia.net/api/v1/users/remilia_jackson/mutual-friends \
-H "Authorization: Bearer $ACCESS_TOKEN"An unknown username returns 404 not_found.
Example JSON response
Illustrative response:
Send a friend request
POST /friendship/requestSends a friend request from the authenticated user to username. RemiliaNET
notifies the other user.
Scope: remilia:social.write · user-delegated token required
curl -X POST https://www.remilia.net/api/v1/friendship/request \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"username": "remilia_jackson"}'A successful request returns {"success": true}. A request to a user who is
already a friend, or who has a pending request with the authenticated user,
returns 400.
Accept a friend request
POST /friendship/acceptAccepts the pending friend request that username sent to the authenticated
user. The body is the same as for Send a friend request.
Scope: remilia:social.write · user-delegated token required
A successful request returns {"success": true}. Accepting a request that is
already accepted also succeeds. Without a pending request from username, the
request returns 400.
Reject a friend request
POST /friendship/rejectRejects the pending friend request that username sent to the authenticated
user. The body is the same as for Send a friend request.
Scope: remilia:social.write · user-delegated token required
A successful request returns {"success": true}, and RemiliaNET notifies
username that the request was declined. Without a pending request from
username, the request returns 400.
Plain-text errors
The friendship endpoints return most 400 errors as plain text, not as the
error envelope. An unknown username, your own username, and a
request in the wrong state return plain text. Only a body that is not valid
JSON returns the envelope.
Global chat
List global chat messages
GET /global-chat/messagesReturns global chat messages, oldest first. The example shows the sample
message sent by Remilia Jackson in the next section. Its ID selects
that message with before. Use IDs from your own responses when you page.
Scope: remilia:chat.read · user-delegated or app-only token
An app with a server can use an app-only token. A user-delegated token also applies the hidden-user and privacy rules of that user.
curl "https://www.remilia.net/api/v1/global-chat/messages?limit=1&before=58576" \
-H "Authorization: Bearer $ACCESS_TOKEN"Example JSON response
When has_more is true, next_cursor passed as before returns the page of
earlier messages. Messages may also carry reply_to_id, media (kind, url,
thumbnail_url, width, height, is_animated), reactions (emoji,
count), and edited_at.
Post a global chat message
POST /global-chat/messagesPosts a text message to global chat as the authenticated user.
Scope: remilia:chat.write · user-delegated token required
curl -X POST https://www.remilia.net/api/v1/global-chat/messages \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text": "gm from Remilia Jackson"}'text is required, up to 8,192 bytes. reply_to_id is optional.
Returns 201 with the created message (same shape as the list) in data.
Example JSON response
Reply response
Illustrative reply. reply_to_id identifies the message being answered.
Directory
Resolve directory identities
POST /directory/resolveReturns matching public identities for up to 50 identifiers in one request.
Duplicate identifiers are returned once, in first-occurrence order. Match
results using query, which echoes the original identifier. identity is
null when no directory-visible user matches. A null identity is a lookup
result, not a login failure or a permission error.
A failed request returns an HTTP status and an error code instead of results. A
401, a 403, a network failure, or a server error is not a missing user. A
user can link an account or change their handle after a lookup, so an earlier
result can be out of date.
Scope: remilia:directory.read · user-delegated or app-only token
An app with a server can use an app-only token.
Identifier type is one of handle, x_handle, github, discord.
Values are trimmed and lowercased. For x_handle, github, and discord, a
leading @ is removed. Deduplication uses the type and normalized value.
More than 50 inputs returns 400 too_many_identifiers, including duplicates.
curl -X POST https://www.remilia.net/api/v1/directory/resolve \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"identifiers": [{"type": "handle", "value": "remilia_jackson"}]}'Example JSON response
Enumerate the user directory
GET /usersPages through all directory-visible users in a stable order, using cursor pagination.
Scope: remilia:directory.read · user-delegated or app-only token
An app with a server can use an app-only token.
curl "https://www.remilia.net/api/v1/users?limit=1" \
-H "Authorization: Bearer $ACCESS_TOKEN"This example requests the first page. next_cursor is an opaque value.
Example JSON response
next_cursor is null on the final page. On other pages, a client passes it
back verbatim as cursor to get the next page.
Errors
Errors use the envelope:
Endpoint-specific codes (invalid_reply, poke_cooldown) are listed with
their endpoints above.
