Skip to main content
POST
Upload from URL
Fetch a remote URL and store the result as a PostQueen media asset. Useful when your media already lives on a CDN or external storage and you do not want to round-trip it through your client.

Requirements for the source URL

  • Must be reachable from the PostQueen backend (publicly resolvable HTTPS, no auth required).
  • The URL path, ignoring any query string, must end in .png, .jpg, .jpeg, .gif, .webp or .mp4. This is checked before the fetch, so AVIF, BMP and TIFF cannot be pulled from a URL at all even though Upload File accepts them.
  • The downloaded bytes are then sniffed and must also land in that same allowlist.
  • PostQueen performs an SSRF-safe fetch: private IP ranges, link-local addresses, and localhost are rejected.

Example

Response shape matches Upload File.

When to prefer multipart upload

If your source URLs are slow or unreliable, the round-trip through PostQueen can fail or take a long time. For best results:
  • Cache stable, fast HTTPS source URLs, such as S3, R2 or Cloudflare Images.
  • For one-off uploads, pre-download the file locally and POST it to /public/v1/upload instead.
  • Do not link to signed URLs that may expire before PostQueen fetches them.
Common failure modes: Uploads troubleshooting.

Authorizations

Authorization
string
header
required

Your PostQueen API key

Body

application/json
url
string<uri>
required

URL of the file to upload

Response

200 - application/json

File uploaded successfully

id
string

Unique file ID

name
string

Stored file name

originalName
string | null

The name the file was uploaded under

path
string

Public URL of the file. This is the value to send as an attachment

thumbnail
string | null

Thumbnail URL, set for video

alt
string | null

Alt text, when one was set