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

Requirements for the source URL

  • Must be reachable from the Postiz backend (publicly resolvable HTTPS, no auth required).
  • Detected MIME type must be in the allowlist documented on Upload File.
  • Postiz performs an SSRF-safe fetch, private IP ranges, link-local addresses, and localhost are rejected. Self-hosted deployments on a trusted private network can disable this with DISABLE_SSRF_PROTECTION.

Example

Response shape matches Upload File. Add "adjust": true to the body to adjust the file to the platforms’ limits after the upload. It works the same as on Upload File.

When to prefer multipart upload

If your source URLs are slow or unreliable, the round-trip through Postiz can fail or take a long time. For best results:
  • Cache stable, fast HTTPS source URLs (S3, R2, Cloudflare Images, etc.).
  • For one-off uploads, pre-download the file locally and POST it to /public/v1/upload instead.
  • Don’t link to signed URLs that may expire before Postiz fetches them.
See Uploads troubleshooting for common failure modes.

Authorizations

Authorization
string
header
required

Your Postiz API key

Body

application/json
url
string<uri>
required

URL of the file to upload

adjust
boolean
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.

Response

200 - application/json

File uploaded successfully

id
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