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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (multipart/form-data, required): object

FieldTypeDescription
file (required)string (binary)At most MAX_UPLOAD_MB (config); type is sniffed and checked against an allowlist.

Responses

StatusMeaningBody
201The staged attachment.MediaAttachment
400Invalid input (INVALID_INPUT): no file, an empty file or too many unsent files.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
413PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON).ErrorResponse
415UNSUPPORTED_MEDIA_TYPE: the file type is not allowed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse
MediaAttachment
FieldTypeDescription
content_typestring
filenamestring
heightinteger
id (required)string (uuid)
is_deleted (required)boolean
mime_type (required)string
original_filename (required)string
sizeinteger
size_bytes (required)integer
url (required)stringURL is /api/media/{id} for members, /api/bot/v1/media/{id} for bots.
widthintegerWidth 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
idpathstring (uuid)yesAttachment ID.

Responses

StatusMeaningBody
204Removed.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: cross-origin request rejected by the CSRF check.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (multipart/form-data, required): object

FieldTypeDescription
contentstringOptional caption.
file (required)string (binary)At most MAX_UPLOAD_MB (config); type is sniffed and checked against an allowlist.
lifetime_secondsintegerThe 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_idstring (uuid)Thread root message ID (reply in a thread).
reply_to_idstring (uuid)Quoted message ID.
tag_idsstringWith title: the post's tags, comma-separated IDs (at most 5, the forum's rules for moderated and required tags apply).
titlestringIn 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

StatusMeaningBody
201Created message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
413PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON).ErrorResponse
415UNSUPPORTED_MEDIA_TYPE: the file type is not allowed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]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_mentionsstring (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
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (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.
forwardForwardRefForward 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_botbooleanIsBot 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_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (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).
noncestring (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)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (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_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle 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

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

NameInTypeRequiredDescription
urlquerystring (uri)yesAbsolute URL of the page (or image) to fetch.

Responses

StatusMeaningBody
200Link card.Preview
204No preview available.
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests or outbound fetch capacity exhausted.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Preview
FieldTypeDescription
authorstringAuthor is the channel, creator or publisher; AuthorURL links to it.
author_urlstring
colorstringColor is the page's theme colour as #rrggbb, for a card accent.
compactbooleanCompact asks for a small thumbnail beside the text (a square avatar or a "summary" card) instead of a wide image above it.
descriptionstring
embedEmbedEmbed is set for videos the client may play inline after a click.
fieldsField[]Fields are short labelled facts such as a price.
imagestringImage is the original absolute image URL; clients load it through the image proxy because the CSP only allows same-origin images.
site_namestringSiteName 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

NameInTypeRequiredDescription
urlquerystring (uri)yesAbsolute URL of the page (or image) to fetch.

Responses

StatusMeaningBody
200Image bytes.string
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the address has no usable image, or the route does not exist.ErrorResponse
410The image was taken down (the address answered 404 or 410). The error code is NOT_FOUND.ErrorResponse
429RATE_LIMITED: too many requests or outbound fetch capacity exhausted.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: 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

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Responses

StatusMeaningBody
200File content; Content-Type is the stored MIME type.string
206Partial content for a Range request.string
304Not modified (If-None-Match).
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
410Media expired or was deleted. The error code is NOT_FOUND.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse

Something wrong on this page? Tell us.