#Media API

#Upload Content

POST /_matrix/media/v3/upload

Upload media content. Returns a content_uri for use in messages.

curl -X POST http://localhost:8899/_matrix/media/v3/upload \
  -H "Authorization: Bearer syt_xxx" \
  -H "Content-Type: image/png" \
  --data-binary @image.png

Response:

{
  "content_uri": "mxc://localhost/abc123",
  "content_type": "image/png",
  "content_length": 12345,
  "media_id": "abc123"
}

#Upload with filename

POST /_matrix/media/v3/upload?filename=document.pdf

#Download Content

GET /_matrix/media/v3/download/{mediaId}
GET /_matrix/media/v3/download/{mediaId}/{fileName}

Returns the raw media content with appropriate Content-Type.

#Create Thumbnail

GET /_matrix/media/v3/thumbnail/{mediaId}?width=64&height=64&method=crop

Thumbnails are cached on disk as thumb_{mediaId}_{w}x{h}_{method}.jpg.

#URL Preview

POST /_matrix/media/v3/preview_url

{
  "url": "https://example.com/article",
  "ts": 1625000000000
}

Response:

{
  "og:title": "Article Title",
  "og:description": "Article description...",
  "og:image": "mxc://localhost/thumb123",
  "og:image:width": 1200,
  "og:image:height": 630,
  "og:url": "https://example.com/article"
}

#SSRF Protection

URL preview validates that the target URL is not an internal/private address:

• Blocks localhost, 127.x.x.x, 10.x.x.x, 192.168.x.x, 172.16-31.x.x
• Blocks IPv6 loopback
• Returns M_FORBIDDEN with HTTP 400 on violation

#Preview Cache

URL preview results are cached in the media_url_preview table with a 3600-second TTL.

#Media Metadata

Uploaded media metadata is stored in the media_metadata table:

#Remote Media

When a federated server sends a media reference, Firmiana downloads and caches the content locally. Connection failures return HTTP 502 (Bad Gateway).