Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
2.6 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: User notes
description: Private notes you keep about other accounts.
---

import RouteHeader from '@/components/RouteHeader.astro';

A note is short private text you keep about another account, and only you can see it. Bots and OAuth2 tokens get 403 `ACCESS_DENIED` on these routes.

## User note object

### Structure

| Field | Type | Description |
| --- | --- | --- |
| note | string | The note text for the target account (1-256 characters) |

## User notes record

A map from target account [snowflake](/snowflakes/) to note text. The Gateway sends the same map in the `notes` field of the [READY](/gateway/events/#ready-object) payload.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| {target_id} | string | The note text for the account with this ID |

### Example

```json
{
  "1501314428688998182": "met at the Berlin meetup",
  "1501314428688998183": "always posts the good links"
}
```

## List user notes

<RouteHeader method="GET" path="/v1/users/@me/notes" />

Returns all your notes as a [user notes record](#user-notes-record), or an empty object when you have none.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [user notes record](#user-notes-record) | Notes were returned |

The rate limit is 60 requests per 10 seconds, on the `user:notes:read` bucket.

## Get user note

<RouteHeader method="GET" path="/v1/users/@me/notes/{target_id}" />

Returns your [user note](#user-note-object) for one account.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [user note](#user-note-object) object | The note was returned |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_USER` when no note is stored for the ID |

The rate limit is 60 requests per 10 seconds, on the `user:notes:read` bucket.

## Set user note

<RouteHeader method="PUT" path="/v1/users/@me/notes/{target_id}" />

Creates, replaces or deletes your note on an account and sends a [User Note Update](/gateway/events/#user-note-update) event to your sessions.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| note? | ?string | The note text (1-256 characters), or null or an empty string to delete the note |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The note was set or deleted |
| 403 | [error response](/http-api/#error-response) | `CONTENT_BLOCKED` when the text matches the instance blocklist |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_USER` when the account does not exist |

The rate limit is 40 requests per 10 seconds, on the `user:notes:write` bucket.