Uploading media

A post can only use media stored in Postra. Get a file into Postra in one of three ways:

Way	Route	Best for
Upload the file	`POST /upload`	Files on your computer or server
Give Postra a link	`POST /upload-from-url`	Files already online, and videos over 50 MB
Reuse a file	`GET /media`	Files already in your Postra media library

Each way gives you a media item with an id and a path. You put those two values in the post.

File types

Postra checks what the file really is, not its name. It accepts:

Images: JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF
Video: MP4

Anything else is refused with 400 and Unsupported file type.

Each platform has its own media rules too, for example how many images a post can have. See Platforms and settings.

Upload a file

POST /upload takes multipart/form-data with the file in a field called file.

curl https://app.postra.co.uk/api/public/v1/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@sourdough.jpg"

Limits:

Limit	Value
Image size	10 MB
Whole request	50 MB. A bigger request is refused with `413`.
Rate	30 uploads per 5 minutes

So a video sent this way must fit in the 50 MB request. For a bigger video, use POST /upload-from-url.

Postra gives every file a new random name. Your own file name is not kept.

Upload from a link

POST /upload-from-url asks Postra to download the file for you.

Body field	Required	Meaning
`url`	yes	Where the file is

curl https://app.postra.co.uk/api/public/v1/upload-from-url \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/media/autumn-menu.mp4"}'

The link must:

be public and start with https://
end in .png, .jpg, .jpeg, .gif, .webp or .mp4 (a query string after it is fine)
point to a file of 100 MB or less

Postra waits up to 60 seconds for the download. The rate limit is 30 requests per 5 minutes.

Error	Cause
`400` with a list of messages	The link is not public HTTPS, or its ending is not on the list
`400 {"msg": "Failed to fetch URL"}`	The server behind the link did not return the file
`400 {"msg": "The file is larger than 100 MB"}`	The file is too big
`400 {"msg": "Unsupported file type."}`	The file is not one of the accepted types

What comes back

Both routes answer 201 with the new media item. The fields you need are id and path:

{
  "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "name": "k3j9x2m1qa.jpg",
  "path": "https://cdn-dev.postra.pl/2026/10/08/k3j9x2m1qa.jpg",
  "type": "image",
  "createdAt": "2026-10-08T10:15:00.000Z"
}

The answer has a few more fields. You can ignore them.

Reuse a file from your media library

GET /media lists the files in your media library, newest first, 18 per page.

Query field	Required	Meaning
`page`	no	Page number, from `1`
`search`	no	Part of the original file name

curl "https://app.postra.co.uk/api/public/v1/media?page=1" \
  -H "Authorization: YOUR_API_KEY"

{
  "pages": 3,
  "results": [
    {
      "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "name": "k3j9x2m1qa.jpg",
      "originalName": "summer-sale.jpg",
      "path": "https://cdn-dev.postra.pl/2026/10/08/k3j9x2m1qa.jpg",
      "createdAt": "2026-10-08T10:15:00.000Z"
    }
  ]
}

search looks at originalName: the name of the file you sent to POST /upload, or the last part of the address you gave POST /upload-from-url. name is the name Postra stored the file under.

Add media to a post

Put the id and path of each item in the image list of a post part. The list can hold up to 20 items, videos included.

curl https://app.postra.co.uk/api/public/v1/posts \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-11-02T09:30:00.000Z",
    "shortLink": false,
    "tags": [],
    "posts": [
      {
        "integration": { "id": "8d3f1c2a-5b6e-4f7a-9c0d-1e2f3a4b5c6d" },
        "value": [
          {
            "content": "Fresh sourdough every Saturday.",
            "image": [
              {
                "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
                "path": "https://cdn-dev.postra.pl/2026/10/08/k3j9x2m1qa.jpg"
              }
            ]
          }
        ],
        "settings": { "post_type": "post" }
      }
    ]
  }'

A path that does not point to Postra’s own storage is refused with 400. Upload the file first, even if it is already online.

Each item can also carry alt, a text description of the image for people who use screen readers. Bluesky and Mastodon publish it with the image.