# Follow or hide a User

> Sets your relationship with a User to `follow` or `hide`.

`PUT /relationships/{username}` on `https://api.mediux.io`

There is one relationship per pair of Users, so setting `hide` replaces a `follow`. The body is limited to 1 KiB. An app can make 50 follow changes per User per day across all apps; hides and clears are not limited. Following a User again within 24 hours of the last follow sends no new Notification. The username matches in any letter case; an unknown, banned or hidden User returns `404`, and naming yourself returns `422` `relationship.self`. Usernames can change, and a freed username can be taken by another User: store the target's `id` and re-read its current `username` (from `GET /relationships` or the profile) before writing.

## Authorization

OAuth 2 bearer token in the `Authorization` header. Required permission: `relationships:manage`.

## Parameters

- `username` (path, string, required): The username of the User to follow, hide or clear, in any letter case.

## Request body (`application/json`)

- `kind` (string, required): One of "follow", "hide".

## Responses

### 200

The relationship now in place.

- `data` (object, required)
  - `kind` (string, required): One of "follow", "hide".
  - `target` (object, required)
    - `id` (string (uuid), required)
    - `username` (string, required)
    - `avatar` (object, nullable, required)
      - `id` (string (uuid), required): Stable image ID, a lowercase UUID. Variant filenames use the same ID.
      - `extension` (string, required): Extension of the Original, such as `png`.
  - `createdAt` (string, required): ISO 8601 UTC instant with milliseconds, such as `2026-11-14T15:03:02.000Z`.

### 400

The request is malformed or failed validation. Inspect `error.code` and `error.issues`.

### 401

The access token is missing (`auth.required`), or invalid, expired or revoked (`auth.invalidToken`).

### 403

The token lacks the required App Permission (`auth.insufficientScope`, with `details.required`), or the account or connection may not do this (`auth.forbidden`).

### 404

The resource does not exist or is not the user's.

### 413

The body exceeds the allowed size.

### 415

The `Content-Type` is not `application/json`.

### 422

A business rule refused the request. Inspect `error.code`.

### 429

Too many requests. Wait the `Retry-After` seconds before trying again.

### 503

Temporarily unavailable. Check the outcome before retrying a write.

## Example response (200)

```json
{
  "data": {
    "kind": "follow",
    "target": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "username": "username",
      "avatar": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "extension": "extension"
      }
    },
    "createdAt": "createdAt"
  }
}
```

## Following and hiding

The path holds the target's username, in any letter case (`/relationships/Koltom`
and `/relationships/koltom` are the same user), and the body holds the
relationship:

```json
{ "kind": "follow" }
```

The response is the resulting row, with the target's stable `id` and current
`username`. Store the `id`: usernames can change, and a freed username can be
taken by another user, so re-read the current `username` (from
`GET /relationships` or the user's profile) before writing. An unknown username
answers `404`. Setting `hide` on a
followed user replaces the follow, because each pair of users has one
relationship.

An app can make 50 follow changes per user each day (UTC), across all apps.
After that, `PUT` answers `429` with `request.rateLimited`,
`details.scope: "follows"` and a `Retry-After`. Hides and clears are not
limited. Following a user again within 24 hours of the last follow sends the
target no second notification.
