server/docs/api/reactions.md

Reactions API

This API is used to send reactions to notes.

Reaction

type UUID = string;

interface NoteReaction {
    name: string;
    count: number;
    me: boolean;
    url: URL;
}

type NoteReactionWithAccounts = NoteReaction & {
    account_ids: UUID[];
}

Get Reactions

All reactions attached to a Status can be found on the note itself, in the reactions field.

Get Users Who Reacted

GET /api/v1/statuses/:id/reactions

Get a list of all the users who reacted to a note. Only IDs are returned, not full account objects, to improve performance on very popular notes.

• Returns: NoteReactionWithAccounts[]
• Authentication: Not required
• Permissions: read:reaction
• Version History:
  • 0.8.0: Added.

Request

Example

GET /api/v1/statuses/123/reactions

Response

200 OK

List of reactions and associated users. The me field is true if the current user has reacted with that emoji.

Data for the custom emoji (e.g. URL) can be found in the emojis field of the Status.

[
    {
        "name": "like",
        "count": 3,
        "me": true,
        "account_ids": ["1", "2", "3"]
    },
    {
        "name": "blobfox-coffee",
        "count": 1,
        "me": false,
        "account_ids": ["4"]
    }
]

Add Reaction

PUT /api/v1/statuses/:id/reactions/:name

Add a reaction to a note.

• Returns: Status
• Authentication: Required
• Permissions: owner:reaction
• Version History:
  • 0.8.0: Added.

Request

• name (string, required): Either a custom emoji shortcode or a Unicode emoji.

Example

PUT /api/v1/statuses/123/reactions/blobfox-coffee
Authorization: Bearer ...

PUT /api/v1/statuses/123/reactions/👍
Authorization: Bearer ...

Response

201 Created

Returns the updated note.

{
    "id": "123",
    ...
    "reactions": [
        {
            "name": "👍",
            "count": 3,
            "me": true
        },
        {
            "name": "blobfox-coffee",
            "count": 1,
            "me": false
        }
    ]
}

Remove Reaction

DELETE /api/v1/statuses/:id/reactions/:name

Remove a reaction from a note.

• Returns: Status
• Authentication: Required
• Permissions: owner:reaction
• Version History:
  • 0.8.0: Added.

Request

• name (string, required): Either a custom emoji shortcode or a Unicode emoji.

Example

DELETE /api/v1/statuses/123/reactions/blobfox-coffee
Authorization: Bearer ...

DELETE /api/v1/statuses/123/reactions
Authorization: Bearer ...

Response

200 OK

Returns the updated note. If the reaction was not found, the note is returned as is.

{
    "id": "123",
    ...
    "reactions": [
        {
            "name": "👍",
            "count": 3,
            "me": true
        }
    ]
}