Upload from a URL

curl --request POST \
  --url https://api.postqueen.ai/public/v1/upload-from-url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/launch-banner.png"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({url: 'https://example.com/launch-banner.png'})
};

fetch('https://api.postqueen.ai/public/v1/upload-from-url', 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-from-url"

payload = { "url": "https://example.com/launch-banner.png" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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-from-url

Upload from a URL

curl --request POST \
  --url https://api.postqueen.ai/public/v1/upload-from-url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/launch-banner.png"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({url: 'https://example.com/launch-banner.png'})
};

fetch('https://api.postqueen.ai/public/v1/upload-from-url', 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-from-url"

payload = { "url": "https://example.com/launch-banner.png" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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"
}

Use this when the file already sits on the web, on a CDN or in public storage, and you do not want to download it and upload it again.

curl -X POST "https://api.postqueen.ai/public/v1/upload-from-url" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch-banner.png"}'

The answer has the same shape as Upload a file: put its id and path on the post.

What the URL must be

A public https:// URL that needs no sign-in. Plain http is refused.
Its path, without the query string, ends in .png, .jpg, .jpeg, .gif, .webp or .mp4. AVIF, BMP, TIFF and MOV files cannot be fetched this way; send them to Upload a file.
It does not point at a private, local or internal address. PostQueen checks the address again when it connects.

How the file is fetched

PostQueen streams the file to storage, up to 1 GB and for at most 5 minutes. A server that declares a larger file is refused before the download starts. Once the file is in, PostQueen reads its type from the bytes, so a .png URL that serves an HTML page fails with Unsupported file type. A video comes back processing, as an upload does: poll Get media status before you post it.

If it fails

Answer	What to do
`400` with a `message` list	The URL is not https, has another extension, or points at an address PostQueen will not fetch
`400 Failed to fetch URL`	The server did not answer with the file in time, or answered with an error. Check that the link opens without signing in
`400 File is too large.`	Over 1 GB
`400 Unsupported file type.`	The bytes are not an image or video PostQueen accepts
`429`	Over 300 uploads from URLs this hour. See Limits and errors

Use stable links. A signed link that expires before PostQueen fetches it fails with Failed to fetch URL.

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

application/json

url

string<uri>

required

URL of 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 from a URL

What the URL must be

How the file is fetched

If it fails

Authorizations

Body

Response

​What the URL must be

​How the file is fetched

​If it fails

Authorizations

Body

Response

What the URL must be

How the file is fetched

If it fails