Media

Upload files (images, videos, documents) to attach to other content. The flow is two-step:

1. Upload the file via POST /media to receive a media object with an id.
2. Reference the id where the media is used. The id must come from an upload by the same token.

Uploads can be used in these places:

• media_ids on POST /walls/{wall_id}/posts
• cover_media_id (an image) on events and calendar entries
• media_ids on staff cards
• media_ids in the image_gallery, video_gallery and document elements of an article

Required scope: write:media for both endpoints. There is no separate read scope, so a read-only token cannot fetch media objects.

Media belongs to the token that uploaded it. GET /media/{id} returns 404 for any other id, including media uploaded in the CMS or the app and media uploaded by another token. The same holds when attaching: an id from another token returns 422 with an error on media_ids (posts, staff cards), cover_media_id (events, calendar entries) or elements (articles). Upload with the token that will attach the media.

Endpoints

Upload request

Send as multipart/form-data:

The API accepts files up to 2,000 MiB (2,097,152,000 bytes), the same limit for every type; a larger file returns 422 with an error on media. A file whose type Monotree can't store returns 422 as well.

That is the effective limit: the web server and PHP on Monotree's servers accept request bodies up to 2,048 MiB, so they never lower it. A request body above 2,048 MiB never reaches the API: the web server answers 413 Request Entity Too Large with an HTML page instead of JSON.

type decides how the file is processed. The type in the response is the kind of file Monotree detected: image or video, or for a document the detected kind, such as pdf, document, spreadsheet, presentation or archive.

curl -X POST https://customer.monotree.com/api/open/v1/media \
  -H "Authorization: Bearer mono_your_token_here" \
  -F "media=@./photo.jpg" \
  -F "type=image"

A successful upload returns 201 with the media object (see Response).

Attach to a post

curl -X POST https://customer.monotree.com/api/open/v1/walls/1/posts \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"body": "Look at this!", "media_ids": [42]}'

Response

{
  "data": {
    "id": 42,
    "type": "image",
    "mime_type": "image/jpeg",
    "filename": "photo.jpg",
    "size": 123456,
    "url": "https://cdn.monotree.dk/.../photo.jpg",
    "width": 1920,
    "height": 1080,
    "tag": null,
    "created_at": "2026-04-24T10:00:00+02:00"
  }
}

tag is always null on /media responses. It is only set when the media is embedded in another resource, such as the QR code on a staff card, where it tells generated attachments from uploads.

A video carries four more fields: