REST: Media
Uploads, downloads and link previews. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
Upload an attachment for a message
POST /api/channels/{channelID}/attachments
multipart/form-data with the file in field 'file'. Stores the file as a staged attachment without posting a message; send the returned id in attachment_ids of POST /api/channels/{channelID}/messages (up to 10 per message). Needs the same permissions as an upload. A staged file is visible only to its uploader and is deleted automatically after six hours if no message claims it. A member holds at most 30 unsent files. Same stricter per-member upload rate limit and size limits as the upload endpoint, and the same removal of metadata from JPEG, PNG and WebP files.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
file (required) | string (binary) | At most MAX_UPLOAD_MB (config); type is sniffed and checked against an allowlist. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The staged attachment. | MediaAttachment |
| 400 | Invalid input (INVALID_INPUT): no file, an empty file or too many unsent files. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Send messages or Attach files permission in the channel, or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | 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. | ErrorResponse |
MediaAttachment
| Field | Type | Description |
|---|---|---|
content_type | string | |
filename | string | |
height | integer | |
id (required) | string (uuid) | |
is_deleted (required) | boolean | |
mime_type (required) | string | |
original_filename (required) | string | |
size | integer | |
size_bytes (required) | integer | |
url (required) | string | URL is /api/media/{id} for members, /api/bot/v1/media/{id} for bots. |
width | integer | Width and Height are a picture's size, measured at upload and kept when the file is removed, so its placeholder takes the same room. Absent for other files and for pictures uploaded before 3.1. |
Remove an unsent attachment
DELETE /api/channels/{channelID}/attachments/{id}
Deletes a staged attachment (one not yet sent in a message) and its file. Only the uploader can. 404 when it does not exist, is not staged any more or belongs to someone else.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
id | path | string (uuid) | yes | Attachment ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Removed. | |
| 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: cross-origin request rejected by the CSRF check. | 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 |
Post a message with an attachment
POST /api/channels/{channelID}/upload
multipart/form-data. Creates a message carrying the file and broadcasts message_create. Works in text and voice channels. Stricter per-member upload rate limit. A JPEG, PNG or WebP is stored without its metadata (EXIF with the GPS position, XMP, IPTC, comments, thumbnails; the orientation stays) and without anything that follows the picture, unless the Owner switched that off, so the stored file and its size_bytes can be smaller than what was sent, never larger.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
content | string | Optional caption. |
file (required) | string (binary) | At most MAX_UPLOAD_MB (config); type is sniffed and checked against an allowlist. |
lifetime_seconds | integer | The message's lifetime: the server deletes it that long after storing it (60 to 2592000, at most the community's ceiling; not for a forum post). Needs the messages.lifetime feature. |
parent_id | string (uuid) | Thread root message ID (reply in a thread). |
reply_to_id | string (uuid) | Quoted message ID. |
tag_ids | string | With title: the post's tags, comma-separated IDs (at most 5, the forum's rules for moderated and required tags apply). |
title | string | In a forum channel: makes the message a post with this title (1 to 100 characters; not with parent_id or reply_to_id). A root message in a forum needs one. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created message. | Message |
| 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 Send messages or Attach files permission in the channel, or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | 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. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them. |
content (required) | string | |
created_at (required) | string (date-time) | |
direct_mentions | string (uuid)[] | DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list. |
display_name (required) | string | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (date-time) | ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock. |
forward | ForwardRef | Forward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward. |
id (required) | string (uuid) | |
is_bot | boolean | IsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message. |
is_edited (required) | boolean | |
is_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (uuid)[] | MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves. |
mentions (required) | string (uuid)[] | Mentions are the users this message mentions (@username, @all, @here). |
nonce | string (uuid) | Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does. |
number (required) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (date-time) | PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone). |
pinned_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title is the required title of a root post in a forum channel (max 100 characters). |
updated_at (required) | string (date-time) | |
user_id (required) | string (uuid) | |
username (required) | string |
Link card for a URL
GET /api/link-preview
Only mounted when LINK_PREVIEWS is enabled. Reads Open Graph and Twitter card tags, the theme colour and oEmbed; YouTube and Vimeo links use the provider's oEmbed, Steam store links add price and recommendations. embed is set for YouTube and Vimeo videos only, with a fixed player address. Answers 204 when the page has no card or may not be fetched. Extra rate limit (120 per minute).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
url | query | string (uri) | yes | Absolute URL of the page (or image) to fetch. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Link card. | Preview |
| 204 | No preview available. | |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests or outbound fetch capacity exhausted. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Preview
| Field | Type | Description |
|---|---|---|
author | string | Author is the channel, creator or publisher; AuthorURL links to it. |
author_url | string | |
color | string | Color is the page's theme colour as #rrggbb, for a card accent. |
compact | boolean | Compact asks for a small thumbnail beside the text (a square avatar or a "summary" card) instead of a wide image above it. |
description | string | |
embed | Embed | Embed is set for videos the client may play inline after a click. |
fields | Field[] | Fields are short labelled facts such as a price. |
image | string | Image is the original absolute image URL; clients load it through the image proxy because the CSP only allows same-origin images. |
site_name | string | SiteName is the provider ("YouTube", "Steam", the page's og:site_name). |
title (required) | string | |
url (required) | string |
Proxied preview image
GET /api/link-preview/image
Only mounted when LINK_PREVIEWS is enabled. Fetches a public image through the server because the CSP only allows same-origin images.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
url | query | string (uri) | yes | Absolute URL of the page (or image) to fetch. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Image bytes. | string |
| 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 address has no usable image, or the route does not exist. | ErrorResponse |
| 410 | The image was taken down (the address answered 404 or 410). The error code is NOT_FOUND. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests or outbound fetch capacity exhausted. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: the image could not be fetched right now; try again. | ErrorResponse |
Download a media object
GET /api/media/{id}
Streams an attachment or avatar. Supports Range and conditional requests. Inline for safe types, attachment otherwise.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | File content; Content-Type is the stored MIME type. | string |
| 206 | Partial content for a Range request. | 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 |
| 410 | Media expired or was deleted. The error code is NOT_FOUND. | 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 |