Relationships¶

A relationship describes a friendship, block, or pending friend request from the caller's perspective. Private notes belong to User notes.

All routes on this page are user-only. They require a user session token (Authorization: Bearer <token>). A valid Bot <token> credential is refused with 403 ACCESS_DENIED, and an invalid one with 401 UNAUTHORIZED.

Relationship object¶

A relationship record belongs to one account and names one other account. Every field describes the owning account's side, and every route on this page returns the caller's own record.

Structure¶

The user object is the ordinary partial user with two additional members:

share_voice_activity is false on every new record. It becomes true on the caller's FRIEND records only when the caller turns voice activity sharing on through Modify voice activity sharing, which rewrites all of the caller's friendships at once.

Example¶

{
  "id": "1501314428688998182",
  "type": 1,
  "relation_type": 1,
  "user": {
    "id": "1501314428688998182",
    "username": "aria",
    "discriminator": "0000",
    "global_name": "Aria",
    "avatar": null,
    "avatar_color": null,
    "flags": 0,
    "name": "Aria",
    "image_url": ""
  },
  "since": "2026-01-14T09:31:00+00:00",
  "nickname": "climbing partner",
  "share_voice_activity": false
}

Relationship types¶

Bulk ignore result object¶

A bulk ignore result reports how many incoming friend requests one call removed.

Structure¶

Bulk ignore filters¶

new_accounts narrows the match only when max_account_age_seconds is also supplied. Without it, and for any value other than new_accounts, the call behaves as all.

Relationship limit¶

One account can hold at most 1000 relationship records in total, counting friendships, blocks, and pending requests in both directions. The limit is fixed and is not instance-configurable.

TEBHOS checks the caller and the target independently when a new friend request is created and when a pending request is accepted. A request fails when either account has reached the limit, with 400 MAX_FRIENDS. Blocking is not subject to the limit.

List relationships¶

GET /users/@me/relationships

Returns every relationship object the caller holds, covering friendships, blocks, and pending requests in both directions.

The operation is not paged, and the whole set comes back in one response. The order is not dependable. A connected client also receives the same set in the Gateway Ready payload.

Response¶

Rate limit¶

40 requests per 10 seconds for each authenticated user, on the user:relationships:list bucket.

Send friend request by username¶

POST /users/@me/relationships

Sends a friend request to the account identified by its username. Returns a relationship object on success.

TEBHOS usernames are unique, so the target is found by username alone and there is no discriminator field. The lookup is case-insensitive and ignores leading and trailing whitespace. Every rule after the lookup is the one described under Send friend request by user ID.

JSON body¶

Response¶

Side effects¶

The side effects are those of Send friend request by user ID.

Rate limit¶

10 requests per 60 seconds for each authenticated user, on the user:friend_request:send bucket, shared with Send friend request by user ID.

Send friend request by user ID¶

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

Sends a friend request to the selected account. Returns a relationship object on success. The route reads no request body.

TEBHOS evaluates the request in this order:

1. A user_id that is not an integer returns 400 BAD_REQUEST, and an ID that names no account returns 404 NOT_FOUND.
2. The caller's own ID returns 400 CANNOT_SEND_FRIEND_REQUEST_TO_SELF.
3. The caller's current record with the target decides the next step:
   • INCOMING_REQUEST: the pending request is accepted, exactly as Accept friend request or block user would, and the resulting FRIEND record is returned.
   • OUTGOING_REQUEST: the existing request is returned unchanged.
   • FRIEND: 400 ALREADY_FRIENDS.
   • BLOCKED (the caller blocked the target): 400 CANNOT_SEND_FRIEND_REQUEST_TO_BLOCKED_USER.
4. A target that has blocked the caller returns 400 FRIEND_REQUEST_BLOCKED. The code is the same as the privacy refusal below, so the caller cannot tell that it is blocked.
5. The target's friend request privacy setting (the friend source flags in user settings) is checked. A target that accepts requests only from friends of friends or from members of a shared guild rejects an unrelated caller with 400 FRIEND_REQUEST_BLOCKED.
6. The relationship limit is checked for both accounts.

Steps 4 to 6 apply only to a genuinely new request. Accepting a pending incoming request (step 3) still checks the relationship limit, but not the privacy setting.

Path parameters¶

Response¶

Side effects¶

A new request writes an OUTGOING_REQUEST record for the caller and an INCOMING_REQUEST record for the target, and emits Relationship Add to both accounts, each with its own record.

When the target had already sent the caller a request, both pending records are replaced with FRIEND records and Relationship Update reaches both accounts.

Returning an existing outgoing request writes nothing and emits nothing.

No path on this route opens a direct message channel.

Rate limit¶

10 requests per 60 seconds for each authenticated user, on the user:friend_request:send bucket, shared with Send friend request by username.

Accept friend request or block user¶

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

Accepts a pending incoming friend request, or blocks the selected account when the body selects BLOCKED. Returns the caller's resulting relationship object.

Both operations return 400 BAD_REQUEST when user_id is malformed or is the caller's own ID, and 404 NOT_FOUND when it names no account.

Acceptance returns 404 UNKNOWN_USER when the caller holds no INCOMING_REQUEST record for the target, then applies the relationship limit to both accounts.

Blocking has no further admission rules. It is not subject to the relationship limit or to the target's privacy settings.

Path parameters¶

JSON body¶

The body can be omitted, in which case acceptance is selected.

Response¶

Side effects¶

Acceptance replaces the pending records on both accounts with FRIEND records, sets since to the current time, and emits Relationship Update to both accounts. It does not open a direct message channel; either side can open one with Create private channel.

Blocking deletes any existing record on both accounts (friendship or pending request in either direction) and writes a BLOCKED record for the caller only. Relationship Add reaches the caller with the block, and Relationship Remove reaches the target with the caller's ID. The Remove is sent even when the target held no record. Blocking an account that is already blocked rewrites the same record. Blocking never closes or deletes the pair's direct message channel.

Rate limit¶

20 requests per 10 seconds for each authenticated user, on the user:friend_request:accept bucket.

Remove relationship¶

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

Removes the caller's friendship, pending friend request in either direction, or block involving the selected account. Returns 204 with an empty body on success.

The route reads no request body. The caller's current record determines what is removed, so the same route unfriends, cancels or declines a request, and unblocks.

Path parameters¶

Response¶

Side effects¶

Removing a friendship or a pending request in either direction removes both accounts' records and emits Relationship Remove to both, each carrying the other account's ID in id. Declining an incoming request therefore also removes the sender's OUTGOING_REQUEST record, and the sender is notified.

A block is stored on one account only, so removing one deletes the caller's record and emits Relationship Remove to the caller alone.

Rate limit¶

30 requests per 10 seconds for each authenticated user, on the user:relationship:delete bucket.

Modify relationship nickname¶

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

Sets or clears the caller's private nickname for a friend. Returns the updated relationship object. Emits a Relationship Update Gateway event to the caller.

Only a FRIEND record accepts a nickname. Every other relationship state returns 404 NOT_FOUND.

Path parameters¶

JSON body¶

The value is stored as sent. The server does not trim it, and a literal empty string is stored as an empty string rather than cleared.

Response¶

Side effects¶

The record changes only for the caller, and share_voice_activity keeps its stored value. A stored since value is preserved, and a record that has none is stamped with the current time. Relationship Update reaches the caller for every accepted request, including one that submits the value already stored.

Rate limit¶

30 requests per 10 seconds for each authenticated user, on the user:relationship:update bucket.

Ignore pending requests in bulk¶

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

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

Matching applies only to the caller's INCOMING_REQUEST records. TEBHOS derives a sender's account age from the timestamp embedded in its snowflake and compares it against max_account_age_seconds as an exclusive upper bound, so a sender exactly that old is not matched. One call removes every matching request.

JSON body¶

The body can be omitted, in which case the all filter applies.

Response¶

Side effects¶

Each matched request removes the caller's INCOMING_REQUEST record and the sender's OUTGOING_REQUEST record, and emits Relationship Remove to the caller and to the sender. A call that matches nothing changes nothing.

A call that fails partway can remove some incoming friend requests and return no count. Call List relationships again to read what remains.

Rate limit¶

5 requests per 60 seconds for each authenticated user, on the relationship:bulk_ignore bucket.

Gateway events¶

Every relationship Dispatch goes only to the sessions of the account it names:

See Gateway events for the envelope.