Skip to main content
POST
/
upload-from-url
Upload from URL
curl --request POST \
  --url https://api.postiz.com/public/v1/upload-from-url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/image.png"
}
'
{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.postiz.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Example

curl -X POST "https://api.postiz.com/public/v1/upload-from-url" \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'
Response shape matches 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

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>