Skip to content

API reference

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:

Loading preview…

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_jackson

The 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.

Loading preview…
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.

Loading preview…

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:

Loading preview…

Get your own profile

GET /me

Returns 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.

Loading preview…
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.

Loading preview…

Shared profile fields

Get your account statistics

GET /me/stats

Returns 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.

Loading preview…

Notifications

List your notifications

GET /me/notifications

Scope: 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
Loading preview…

count, from, guild_name, and message appear only on notification types that carry them.

Beetle

Get your Beetle state

GET /me/beetle

Returns 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
Loading preview…

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.

Loading preview…

List your discovered Beetle cards

GET /me/beetle/cards

Returns 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
Loading preview…

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/cooldowns

Returns 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:

Loading preview…

Pokes

Poke a user

POST /users/{handle}/poke

Sends 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:

Loading preview…
Cooldown error

Illustrative repeat poke:

Loading preview…

Get the poke cooldown

GET /users/{handle}/poke/cooldown

Returns 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:

Loading preview…

Friends

List mutual friends

GET /users/{username}/mutual-friends

Returns 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:

Loading preview…

Send a friend request

POST /friendship/request

Sends 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/accept

Accepts 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/reject

Rejects 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/messages

Returns 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
Loading preview…

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/messages

Posts 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
Loading preview…
Reply response

Illustrative reply. reply_to_id identifies the message being answered.

Loading preview…

Directory

Resolve directory identities

POST /directory/resolve

Returns 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
Loading preview…

Enumerate the user directory

GET /users

Pages 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
Loading preview…

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:

Loading preview…

Endpoint-specific codes (invalid_reply, poke_cooldown) are listed with their endpoints above.