Upload a file

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

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

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

options.body = form;

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

import requests

url = "https://api.postqueen.ai/public/v1/upload"

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

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

print(response.text)

{
  "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e",
  "name": "a1b2c3d4e5.png",
  "originalName": "launch-banner.png",
  "path": "https://cdn.example.com/a1b2c3d4e5.png",
  "thumbnail": null,
  "alt": null,
  "status": "ready"
}

POST

upload

Upload a file

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

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

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

options.body = form;

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

import requests

url = "https://api.postqueen.ai/public/v1/upload"

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

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

print(response.text)

{
  "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e",
  "name": "a1b2c3d4e5.png",
  "originalName": "launch-banner.png",
  "path": "https://cdn.example.com/a1b2c3d4e5.png",
  "thumbnail": null,
  "alt": null,
  "status": "ready"
}

Send the file as multipart form data in a field named file. The answer’s id and path go into a post’s image array.

curl -X POST "https://api.postqueen.ai/public/v1/upload" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@launch-banner.png"

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("launch-banner.png")]), "launch-banner.png");

const res = await fetch("https://api.postqueen.ai/public/v1/upload", {
  method: "POST",
  headers: { Authorization: process.env.POSTQUEEN_API_KEY },
  body: form,
});
const media = await res.json();

Then, in the post:

"image": [
  {
    "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e",
    "path": "https://cdn.example.com/a1b2c3d4e5.png"
  }
]

What it accepts

PostQueen reads the type from the file’s bytes, not its name, and stores files up to 1 GB. Each network then has its own, much smaller limits when it publishes.

Type	Stored	Can go on a post
JPEG, PNG, GIF, WebP	Yes	Yes
MP4	Yes, after processing	Yes, once `ready`
MOV	Yes, converted to MP4	Yes, once `ready`
AVIF, BMP, TIFF	Yes	No: a post’s media must end in .png, .jpg, .jpeg, .gif, .webp or .mp4

Videos are processed first

A video answers with "status": "processing" while PostQueen prepares it for the networks. Poll Get media status until it is ready, then use the path that call returns: a converted file has a new one. Images are ready at once.

POST /upload allows 300 requests an hour per workspace, counted apart from Upload from a URL and from the posting limit. See Limits and errors.

Authorizations

Authorization

string

header

required

Your API key from Connections > API Keys, or an OAuth access token (pos_...). Send it as it is, with no Bearer prefix.

Body

multipart/form-data

file

required

The file to upload

Response

Stored

string

Unique file ID

name

string

Stored file name

originalName

string | null

The name the file was uploaded under

path

string

URL of the stored file. Send it with id as a post's media

thumbnail

string | null

Thumbnail URL, set for video

alt

string | null

Alt text, when one was set

status

enum<string>

A video (MP4 or MOV) is normalized in the background and starts as processing; poll GET /media/{id}/status until it is ready before you put it on a post. Images are ready at once.

Available options:

ready,

processing,

failed

Last modified on September 23, 2026

Get started

Endpoints

Posting settings by network

Build on PostQueen

SDK and no-code

Upload a file

What it accepts

Videos are processed first

Authorizations

Body

Response

​What it accepts

​Videos are processed first

Authorizations

Body

Response

What it accepts

Videos are processed first