Skip to main content
POST
/
public
/
v1
/
upload
Upload Media
curl --request POST \
  --url https://api.example.com/public/v1/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>"
}
'
{
  "400": {},
  "401": {},
  "413": {},
  "415": {},
  "id": "<string>",
  "path": "<string>",
  "name": "<string>"
}

​
Overview

Upload media files (images, videos, documents) to Postiz. Returns a media object with a path URL that can be used in post creation requests. Postiz provides two upload methods:
  1. File Upload - Upload files directly from your local system
  2. URL Upload - Upload files from a URL

​
File Upload

Upload a file using multipart/form-data.

​
Request

​
file
file
required
The file to upload. Supports:
  • Images: PNG, JPG, JPEG, GIF, WEBP, SVG, BMP, ICO
  • Videos: MP4, MOV, AVI, MKV, WEBM, FLV, WMV, M4V, MPEG, 3GP
  • Audio: MP3, WAV, OGG, AAC, FLAC, M4A
  • Documents: PDF, DOC, DOCX

​
Response

​
id
string
Unique identifier for the uploaded media
​
path
string
Full URL to the uploaded media. Use this value in the image array when creating posts.
​
name
string
Original filename of the uploaded media

​
Examples

curl -X POST https://api.postiz.com/public/v1/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

​
URL Upload

Upload a file from a URL without downloading it locally first.

​
Endpoint

POST /public/v1/upload-from-url

​
Request

​
url
string
required
URL of the file to upload. Must be a valid image, video, or document URL with appropriate file extension.

​
Examples

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/image.jpg"
  }'

​
Response Example

{
  "id": "media-abc123",
  "path": "https://cdn.postiz.com/uploads/org-456/image-abc123.jpg",
  "name": "image.jpg"
}

​
Using Uploaded Media in Posts

After uploading, use the returned path in your post creation request: 
const postiz = new Postiz('YOUR_API_KEY');

// 1. Upload media
const fileBuffer = readFileSync('photo.jpg');
const media = await postiz.upload(fileBuffer, 'photo.jpg');

// 2. Create post with media
await postiz.post({
  type: 'schedule',
  date: '2024-12-31T12:00:00Z',
  shortLink: true,
  tags: [],
  posts: [{
    integration: { id: 'twitter-id' },
    value: [{
      content: 'Beautiful sunset!',
      image: [{
        id: media.id,      // Use the ID from upload response
        path: media.path   // Use the path from upload response
      }]
    }]
  }]
});

​
Multiple Media Files

Upload and attach multiple media files to a post: 
const postiz = new Postiz('YOUR_API_KEY');

// Upload multiple files
const media1 = await postiz.upload(
  readFileSync('photo1.jpg'),
  'photo1.jpg'
);
const media2 = await postiz.upload(
  readFileSync('photo2.jpg'),
  'photo2.jpg'
);
const media3 = await postiz.upload(
  readFileSync('video.mp4'),
  'video.mp4'
);

// Create post with multiple media
await postiz.post({
  type: 'schedule',
  date: '2024-12-31T12:00:00Z',
  shortLink: true,
  tags: [],
  posts: [{
    integration: { id: 'twitter-id' },
    value: [{
      content: 'Check out these photos and video!',
      image: [
        { id: media1.id, path: media1.path },
        { id: media2.id, path: media2.path },
        { id: media3.id, path: media3.path }
      ]
    }]
  }]
});

​
Supported File Types

​
Images

ExtensionMIME TypeNotes
.pngimage/pngRecommended for graphics
.jpg, .jpegimage/jpegRecommended for photos
.gifimage/gifSupports animation
.webpimage/webpModern format
.svgimage/svg+xmlVector graphics
.bmpimage/bmpBitmap
.icoimage/x-iconIcons

​
Videos

ExtensionMIME TypeNotes
.mp4video/mp4Most compatible
.movvideo/quicktimeApple format
.avivideo/x-msvideoWindows format
.mkvvideo/x-matroskaHigh quality
.webmvideo/webmWeb optimized
.flvvideo/x-flvFlash video
.wmvvideo/x-ms-wmvWindows Media
.m4vvideo/x-m4vApple format
.mpeg, .mpgvideo/mpegMPEG format
.3gpvideo/3gppMobile format

​
Audio

ExtensionMIME Type
.mp3audio/mpeg
.wavaudio/wav
.oggaudio/ogg
.aacaudio/aac
.flacaudio/flac
.m4aaudio/mp4

​
Documents

ExtensionMIME Type
.pdfapplication/pdf
.docapplication/msword
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document

​
File Size Limits

File size limits depend on your platform and plan:
  • Images: Typically up to 10MB
  • Videos: Varies by platform (e.g., Twitter: 512MB, LinkedIn: 200MB)
  • Documents: Up to 10MB
Check platform-specific limits before uploading.

​
Error Responses

​
400
Bad Request
Missing file or invalid URL
{
  "msg": "No file provided"
}
​
401
Unauthorized
Invalid or missing API key
{
  "msg": "Invalid API key"
}
​
413
Payload Too Large
File size exceeds limits
{
  "statusCode": 413,
  "message": "File too large"
}
​
415
Unsupported Media Type
File type not supported
{
  "statusCode": 415,
  "message": "Unsupported file type"
}

​
Best Practices

Compress images and videos before uploading to reduce storage costs and improve post performance.
  • Use JPEG for photos
  • Use PNG for graphics with transparency
  • Use MP4 for videos (best compatibility)
Include alt text in the media object for accessibility:
{
  id: media.id,
  path: media.path,
  alt: "Description of the image for screen readers"
}
Check file types and sizes client-side before uploading to avoid API errors.

​
Next Steps

Create Post

Use uploaded media in posts

Media Library

Learn about media management

Build docs developers (and LLMs) love

Get started for freeTalk to us