Relationships

A relationship is a friendship, block or pending friend request, seen from one account. Only user tokens can call these routes, and bot and OAuth2 tokens get 403 ACCESS_DENIED.

Each account has its own record. A friendship is a FRIEND record on both accounts, a pending request is OUTGOING_REQUEST on the sender and INCOMING_REQUEST on the recipient, and a block is a BLOCKED record on the blocker only.

Relationship object

Structure

Field	Type	Description
id	snowflake	The ID of the related account
type	integer	The relationship type
user	partial user object	The related account
since?	ISO8601 timestamp	When the record got its current type
nickname	?string	Your private nickname for the related account
share_voice_activity	boolean	Whether you share voice activity with the related account
friend_shares_voice_activity1	boolean	Whether the related account shares voice activity with you

¹ Only List relationships and the Relationship Update sent by Modify voice activity sharing return the real value. Everything else returns true.

Example

{
  "id": "1501314428688998182",
  "type": 1,
  "user": {"id": "1501314428688998182", "username": "aria", "discriminator": "0042"},
  "since": "2026-01-14T09:31:00.000Z",
  "nickname": "climbing partner",
  "share_voice_activity": true,
  "friend_shares_voice_activity": false
}

Relationship types

Value	Name	Description
1	FRIEND	The two accounts are friends
2	BLOCKED	You have blocked the related account
3	INCOMING_REQUEST	The related account has sent you a friend request
4	OUTGOING_REQUEST	You have sent the related account a friend request

Bulk ignore result object

Structure

Field	Type	Description
ignored_count	integer	The number of incoming friend requests removed

Bulk ignore filters

Value	Name	Description
all	All	Matches every incoming friend request
new_accounts	New accounts	Matches senders whose accounts are younger than max_account_age_seconds, or every request when it is left out

Relationship limit

The max_relationships limit caps the friendships, blocks and pending requests one account has, and defaults to 1000. Adding a record fails with 400 MAX_FRIENDS when either account is at the limit, and the error has a max_relationships field with the limit. Bot accounts have no limit, and blocking skips the check.

List relationships

GET/v1/users/@me/relationships

Returns every relationship you have, in no particular order.

Response

Status	Body	Condition
200	array[relationship object]	Relationships were returned

The rate limit is 40 requests per 10 seconds, on the user:relationships:list bucket.

Send friend request by tag

POST/v1/users/@me/relationships

Sends a friend request to the account with the given username and discriminator, under the rules of Send friend request by user ID. Returns a relationship object.

JSON body

Field	Type	Description
username	string	The username of the target (1-32 characters)
discriminator?	string | integer	The discriminator of the target (1-4 digits)

You can leave out the discriminator only when the instance tag style is none.

Response

Status	Body	Condition
200	relationship object	The request or friendship was returned
400	error response	NO_USERS_WITH_FLUXERTAG_EXIST, DISCRIMINATOR_REQUIRED, ALREADY_FRIENDS, or a code from the user ID route
403	error response	UNCLAIMED_ACCOUNT_CANNOT_SEND_FRIEND_REQUESTS, FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED or NEW_CONVERSATIONS_LIMITED

The rate limit is 10 requests per minute, on the user:friend_request:send bucket.

Send friend request by user ID

POST/v1/users/@me/relationships/{user_id}

Sends a friend request to an account, or accepts the account's pending request to you. Returns a relationship object.

JSON body

The body is optional.

Field	Type	Description
staff_force_accept?	boolean	Whether to make the accounts friends directly, skipping blocks, friend source flags and the limit (STAFF only)

Response

Status	Body	Condition
200	relationship object	The request or friendship was returned
400	error response	One of the codes below
403	error response	UNCLAIMED_ACCOUNT_CANNOT_SEND_FRIEND_REQUESTS, FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED or NEW_CONVERSATIONS_LIMITED
404	error response	UNKNOWN_USER when the account does not exist

A 400 has one of these codes.

Code	Condition
FRIENDS_DISABLED	The community policy sets friends_disabled
CANNOT_SEND_FRIEND_REQUEST_TO_SELF	The target is you
CANNOT_SEND_FRIEND_REQUEST_TO_BLOCKED_USER	You have blocked the target
FRIEND_REQUEST_BLOCKED	The target is deleted, blocked you, is a bot without FRIENDLY_BOT or excludes you
MAX_FRIENDS	You are at the relationship limit

If you already have a friendship or outgoing request with the account, it comes back unchanged, and a pending request from the account is accepted. A new request sends Relationship Add to both accounts, and an acceptance sends Relationship Update to both. A bot with FRIENDLY_BOT and without FRIENDLY_BOT_MANUAL_APPROVAL accepts at once, and the response is then the bot's record, with your account as user. Accepting through this route does not open a direct message.

The rate limit is 10 requests per minute, on the user:friend_request:send bucket.

Accept request or block user

PUT/v1/users/@me/relationships/{user_id}

Accepts a pending incoming friend request, or blocks the account when type is BLOCKED. Returns a relationship object.

JSON body

The body is optional. Any type other than BLOCKED, or no body, accepts a pending incoming request.

Field	Type	Description
type?	integer	The relationship type. Send BLOCKED to block the account

Response

Status	Body	Condition
200	relationship object	The friendship or the block was returned
400	error response	One of the codes below
403	error response	Your account is unclaimed, or unverified while interaction_tier is enforced
404	error response	UNKNOWN_USER when the account does not exist, or when accepting and no incoming request exists

A 400 has one of these codes.

Code	Condition
FRIENDS_DISABLED	The community policy sets friends_disabled and you are accepting
FRIEND_REQUEST_BLOCKED	Either account is deleted
CANNOT_BLOCK_SYSTEM_USER	The block target is the Fluxer system account
MAX_FRIENDS	You are at the relationship limit

A 403 has UNCLAIMED_ACCOUNT_CANNOT_ACCEPT_FRIEND_REQUESTS or FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED.

Accepting sends Relationship Update to both accounts, opens your direct message with the account for both of you, and sends Channel Create to whoever did not already have it open.

Blocking replaces any friendship or pending request with a BLOCKED record and sends Relationship Add to you. If the block ends a friendship or your outgoing request, the other account's record is deleted too and it gets Relationship Remove. Blocking works even when friends are disabled or your account is unclaimed, and it does not close the direct message.

The rate limit is 20 requests per 10 seconds, on the user:friend_request:accept bucket.

Remove relationship

DELETE/v1/users/@me/relationships/{user_id}

Removes your friendship, pending request in either direction, or block with an account. Returns 204 with an empty body.

Response

Status	Body	Condition
204	empty	The relationship was removed
404	error response	UNKNOWN_USER when you have no relationship with the account

Removing a friendship or outgoing request deletes both records and sends Relationship Remove to both accounts. Removing a block or declining an incoming request deletes only your record and sends the event only to you, and the sender keeps its OUTGOING_REQUEST.

The rate limit is 30 requests per 10 seconds, on the user:relationship:delete bucket.

Modify relationship nickname

PATCH/v1/users/@me/relationships/{user_id}

Sets or clears your private nickname for a friend, which the friend never sees. Returns the updated relationship object and sends Relationship Update to you.

JSON body

Field	Type	Description
nickname	?string	The nickname (up to 256 characters), or null to clear it

Response

Status	Body	Condition
200	relationship object	The updated relationship was returned
404	error response	UNKNOWN_USER when the account is not your friend

The rate limit is 30 requests per 10 seconds, on the user:relationship:update bucket.

Ignore pending requests in bulk

POST/v1/users/@me/relationships/bulk-ignore

Removes your matching incoming friend requests. Returns a bulk ignore result object.

JSON body

The body is optional.

Field	Type	Description
filter?	string	The bulk ignore filter (default all)
max_account_age_seconds?	integer	With new_accounts, only match senders whose accounts are younger than this many seconds

Response

Status	Body	Condition
200	bulk ignore result object	Matching requests were removed

Each match deletes both records and sends Relationship Remove to you and the sender.

The rate limit is 5 requests per minute, on the user:friend_request:bulk_ignore bucket.