REST: Emoji
Custom emoji of the community: list, images and (with Manage emoji) upload, rename and delete. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
Add a custom emoji
POST /api/admin/emoji
multipart/form-data with name (2 to 32 characters of a-z, 0-9 and _; upper case is folded) and file, a PNG, GIF or WebP of at most 256 KiB. The image is decoded and redrawn (at most 128x128, no metadata); SVG, JPEG and animated WebP are refused. Needs Manage emoji. Broadcasts emoji_changed.
Authentication: Session cookie
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
file (required) | string (binary) | PNG, GIF or WebP, at most 256 KiB. |
name (required) | string | Emoji name. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created emoji. | Emoji |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: the name is taken or the instance limit is reached. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON). | ErrorResponse |
| 415 | UNSUPPORTED_MEDIA_TYPE: the file type is not allowed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available, or image processing is busy. | ErrorResponse |
Emoji
| Field | Type | Description |
|---|---|---|
animated (required) | boolean | Animated emoji are GIFs and have a still frame for reduced motion. |
created_at (required) | string | |
id (required) | string (uuid) | |
name (required) | string | |
still_url | string | StillURL is the first frame (animated emoji only). |
url (required) | string | URL serves the image; it changes with the content (the v parameter), so it may be cached for good. |
Delete a custom emoji
DELETE /api/admin/emoji/{id}
Messages and reactions that used it show :name: as text from now on. Needs Manage emoji. Broadcasts emoji_changed.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Emoji ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Rename a custom emoji
PATCH /api/admin/emoji/{id}
Messages and reactions keep pointing at the emoji by id, so they follow the new name. Needs Manage emoji. Broadcasts emoji_changed.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Emoji ID. |
Request body (application/json, required): RenameRequest
| Field | Type | Description |
|---|---|---|
name (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Renamed emoji. | Emoji |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the name is taken. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Emoji
| Field | Type | Description |
|---|---|---|
animated (required) | boolean | Animated emoji are GIFs and have a still frame for reduced motion. |
created_at (required) | string | |
id (required) | string (uuid) | |
name (required) | string | |
still_url | string | StillURL is the first frame (animated emoji only). |
url (required) | string | URL serves the image; it changes with the content (the v parameter), so it may be cached for good. |
List custom emoji
GET /api/emoji
Every custom emoji of the instance, by name, with the instance limit. Members use them as <:name:id> in messages and reactions.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Custom emoji. | List |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
List
| Field | Type | Description |
|---|---|---|
emoji (required) | Emoji[] | |
limit (required) | integer | Limit is how many custom emoji the instance allows (EMOJI_MAX). |
Custom emoji image
GET /api/emoji/{id}/image
The redrawn PNG or GIF of the emoji. The v parameter is the content hash of the emoji's URL: the response is cacheable for a year.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Emoji ID. |
v | query | string | no | Content hash from the emoji's URL. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Image. | string |
| 304 | Not modified (If-None-Match). | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available. | ErrorResponse |
Custom emoji still frame
GET /api/emoji/{id}/still
The first frame of an animated emoji as a PNG, for members who reduce motion. 404 when the emoji has no still frame (it is not animated). The v parameter is the content hash of the emoji's URL: the response is cacheable for a year.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Emoji ID. |
v | query | string | no | Content hash from the emoji's URL. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Image. | string |
| 304 | Not modified (If-None-Match). | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available. | ErrorResponse |