A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Relationships
description: Friends, blocks and pending friend requests for the current user.
---
import RouteHeader from '@/components/RouteHeader.astro';
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](#relationship-types) |
| user | [partial user](/http-api/users/#partial-user-object) 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_activity<sup>1</sup> | boolean | Whether the related account shares voice activity with you |
<sup>1</sup> Only [List relationships](#list-relationships) and the [Relationship Update](/gateway/events/#relationship-update) sent by [Modify voice activity sharing](/http-api/users/settings/#modify-voice-activity-sharing) return the real value. Everything else returns `true`.
### Example
```json
{
"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](/http-api/instance/#limit-keys) 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
<RouteHeader method="GET" path="/v1/users/@me/relationships" />
Returns every [relationship](#relationship-object) you have, in no particular order.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[relationship](#relationship-object) object] | Relationships were returned |
The rate limit is 40 requests per 10 seconds, on the `user:relationships:list` bucket.
## Send friend request by tag
<RouteHeader method="POST" path="/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](#send-friend-request-by-user-id). Returns a [relationship](#relationship-object) 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](#relationship-object) object | The request or friendship was returned |
| 400 | [error response](/http-api/#error-response) | `NO_USERS_WITH_FLUXERTAG_EXIST`, `DISCRIMINATOR_REQUIRED`, `ALREADY_FRIENDS`, or a code from [the user ID route](#send-friend-request-by-user-id) |
| 403 | [error response](/http-api/#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
<RouteHeader method="POST" path="/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](#relationship-object) 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](#relationship-object) object | The request or friendship was returned |
| 400 | [error response](/http-api/#error-response) | One of the codes below |
| 403 | [error response](/http-api/#error-response) | `UNCLAIMED_ACCOUNT_CANNOT_SEND_FRIEND_REQUESTS`, `FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED` or `NEW_CONVERSATIONS_LIMITED` |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_USER` when the account does not exist |
A 400 has one of these codes.
| Code | Condition |
| --- | --- |
| `FRIENDS_DISABLED` | The [community policy](/http-api/instance/#community-policy-object) 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](/http-api/users/#friend-source-flags) |
| `MAX_FRIENDS` | You are at the [relationship limit](#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](/gateway/events/#relationship-add) to both accounts, and an acceptance sends [Relationship Update](/gateway/events/#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
<RouteHeader method="PUT" path="/v1/users/@me/relationships/{user_id}" />
Accepts a pending incoming friend request, or blocks the account when `type` is `BLOCKED`. Returns a [relationship](#relationship-object) 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](#relationship-types). Send `BLOCKED` to block the account |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [relationship](#relationship-object) object | The friendship or the block was returned |
| 400 | [error response](/http-api/#error-response) | One of the codes below |
| 403 | [error response](/http-api/#error-response) | Your account is unclaimed, or unverified while [`interaction_tier`](/http-api/users/#account-tiers) is `enforced` |
| 404 | [error response](/http-api/#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](/http-api/instance/#community-policy-object) 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](#relationship-limit) |
A 403 has `UNCLAIMED_ACCOUNT_CANNOT_ACCEPT_FRIEND_REQUESTS` or `FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED`.
Accepting sends [Relationship Update](/gateway/events/#relationship-update) to both accounts, opens your direct message with the account for both of you, and sends [Channel Create](/gateway/events/#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](/gateway/events/#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](/gateway/events/#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
<RouteHeader method="DELETE" path="/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](/http-api/#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](/gateway/events/#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
<RouteHeader method="PATCH" path="/v1/users/@me/relationships/{user_id}" />
Sets or clears your private nickname for a friend, which the friend never sees. Returns the updated [relationship](#relationship-object) object and sends [Relationship Update](/gateway/events/#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](#relationship-object) object | The updated relationship was returned |
| 404 | [error response](/http-api/#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
<RouteHeader method="POST" path="/v1/users/@me/relationships/bulk-ignore" />
Removes your matching incoming friend requests. Returns a [bulk ignore result](#bulk-ignore-result-object) object.
### JSON body
The body is optional.
| Field | Type | Description |
| --- | --- | --- |
| filter? | string | The [bulk ignore filter](#bulk-ignore-filters) (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](#bulk-ignore-result-object) object | Matching requests were removed |
Each match deletes both records and sends [Relationship Remove](/gateway/events/#relationship-remove) to you and the sender.
The rate limit is 5 requests per minute, on the `user:friend_request:bulk_ignore` bucket.