Upload File

POST

upload

Upload a file

curl --request POST \
  --url https://api.postiz.com/public/v1/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form adjust=false

import requests

url = "https://api.postiz.com/public/v1/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "adjust": "false" }
headers = {"Authorization": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('adjust', 'false');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.postiz.com/public/v1/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.postiz.com/public/v1/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.postiz.com/public/v1/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.postiz.com/public/v1/upload")
  .header("Authorization", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.postiz.com/public/v1/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e",
  "name": "image.png",
  "path": "https://uploads.postiz.com/image.png",
  "organizationId": "85460a39-6329-4cf4-a252-187ce89a3480",
  "createdAt": "2024-12-14T08:18:54.274Z",
  "updatedAt": "2024-12-14T08:18:54.274Z"
}

Upload a media file by multipart form. Returns an id and path you can pass into a post’s image array.

Accepted MIME types

The backend inspects the file’s actual content (not just the extension) and rejects anything outside this allowlist:

Type	MIME
JPEG	`image/jpeg`
PNG	`image/png`
GIF	`image/gif`
WebP	`image/webp`
AVIF	`image/avif`
BMP	`image/bmp`
TIFF	`image/tiff`
MP4 video	`video/mp4`

PDFs are not accepted. See Uploads troubleshooting for limits and recommended video formats.

Example

curl -X POST "https://api.postiz.com/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "file=@photo.jpg"

Example response:

{
  "id": "01HXYZ123ABCDEF",
  "path": "https://uploads.postiz.com/photo.jpg",
  "status": "ready"
}

Adjusting media to platform limits

Platforms reject media that is too large, too small or in an encoding they don’t accept. Send the optional adjust field as true to adjust the file after the upload. It defaults to false, which stores the file as uploaded.

Videos get their short side scaled to 1080 px, up or down, with the long side at most 1920 px. They are re-encoded to H.264 MP4 (yuv420p, at most 60 fps) with AAC audio (128 kbps, 48 kHz) and the metadata moved to the start of the file for streaming.
Images are only scaled down, to a short side of at most 1080 px and a long side of at most 1920 px, and keep their format.
GIF, AVIF, BMP and TIFF files are stored as uploaded.

curl -X POST "https://api.postiz.com/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "adjust=true" \
  -F "file=@video.mp4"

The adjustment runs in the background, so the response comes back with "status": "processing". The adjusted file replaces the original at the same path, usually within seconds. Poll Media Status every few seconds and wait until the status is ready before publishing a post with this path: a post published while it is processing uses the original, unadjusted file. Without adjust the upload is synchronous and the path is ready immediately. If the adjustment fails, the original file is kept and used for publishing, and Media Status returns "status": "ready" with a warning.

On self-hosted instances without the media processor configured, adjust has no effect and the file is stored as uploaded with "status": "ready".

Usage in a post

{
  "image": [
    {
      "id": "01HXYZ123ABCDEF",
      "path": "https://uploads.postiz.com/photo.jpg"
    }
  ]
}

Authorizations

Authorization

string

header

required

Your Postiz API key

Body

multipart/form-data

file

required

The file to upload

adjust

enum<string>

default:false

Adjust the file to the platforms' limits after the upload: videos are scaled to a 1080 px short side (long side at most 1920 px) and re-encoded to H.264 MP4 with AAC audio, images larger than that are scaled down. Runs in the background, poll GET /media/{id}/status for the result. Defaults to false.

Available options:

true,

false

Response

200 - application/json

File uploaded successfully

string

Unique file ID

name

string

File name

path

string

File URL

organizationId

string

createdAt

string<date-time>

updatedAt

string<date-time>

status

enum<string>

"processing" while an upload with adjust set to true is being adjusted, otherwise "ready"

Available options:

ready,

processing

Upload a file

curl --request POST \
  --url https://api.postiz.com/public/v1/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form adjust=false

import requests

url = "https://api.postiz.com/public/v1/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "adjust": "false" }
headers = {"Authorization": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('adjust', 'false');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.postiz.com/public/v1/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.postiz.com/public/v1/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.postiz.com/public/v1/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.postiz.com/public/v1/upload")
  .header("Authorization", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.postiz.com/public/v1/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"adjust\"\r\n\r\nfalse\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e",
  "name": "image.png",
  "path": "https://uploads.postiz.com/image.png",
  "organizationId": "85460a39-6329-4cf4-a252-187ce89a3480",
  "createdAt": "2024-12-14T08:18:54.274Z",
  "updatedAt": "2024-12-14T08:18:54.274Z"
}

Overview

Integrations

Posts

Analytics

Notifications

Uploads

Video Generation

Clipping

Provider settings

Accepted MIME types

Example

Adjusting media to platform limits

Usage in a post

Authorizations

Body

Response

​Accepted MIME types

​Example

​Adjusting media to platform limits

​Usage in a post

Authorizations

Body

Response

Accepted MIME types

Example

Adjusting media to platform limits

Usage in a post