Skip to main content
Before you can attach an image or video to a scheduled post, you need to upload it to the Volta media library. The upload endpoint accepts standard media files via a multipart form request and returns an ID you can pass directly into the image field of a post’s content object. Uploaded files are stored in your instance’s configured storage backend — local disk by default, or Cloudflare R2 if configured.

​
POST /public/v1/upload

Upload a media file to the Volta media library. The file is stored and made available for use in posts. You can reference the returned id in the image array when scheduling a post with POST /public/v1/posts.

​
Request

This endpoint uses multipart/form-data rather than JSON. Do not set Content-Type: application/json for this request — let your HTTP client set the multipart boundary automatically.
​
file
file
required
The media file to upload. Attach it as a form field named file.

​
Supported file types

TypeExtensions
Imagepng, jpg, jpeg, gif
Videomp4

​
Example

curl -X POST https://your-instance.com/public/v1/upload \
  -H 'Authorization: your-api-key' \
  -F 'file=@./image.png'

​
Response

{ "id": "media_xyz789", "url": "https://your-instance.com/uploads/image.png" }
​
id
string
The unique identifier for the uploaded file. Pass this value in the image array when creating a post.
​
url
string
The publicly accessible URL of the uploaded file.

​
Using the uploaded media in a post

After uploading, reference the returned id in the image array of your post content: 
curl -X POST https://your-instance.com/public/v1/posts \
  -H 'Authorization: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "schedule",
    "date": "2025-01-15T10:00:00",
    "posts": [
      {
        "integration": { "id": "channel-id" },
        "value": [
          {
            "content": "Check out this image!",
            "image": ["media_xyz789"]
          }
        ]
      }
    ]
  }'
If you are using the @postsider/node SDK, the client.upload(file, extension) method handles buffer-to-form-data conversion for you automatically. Pass a Node.js Buffer and the file extension string (e.g. 'png'), and the SDK handles the multipart encoding and MIME type mapping. See the SDK Reference for details.
Make sure the file extension you provide matches the actual file content. Mismatched MIME types may cause upload failures or rendering issues on certain social platforms.