> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Volta API Media Upload: POST /public/v1/upload Endpoint

> Upload images and videos to Volta's media library via POST /public/v1/upload. Returns a media ID you can attach to scheduled posts.

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.

<ParamField body="file" type="file" required>
  The media file to upload. Attach it as a form field named `file`.
</ParamField>

### Supported file types

| Type  | Extensions                  |
| ----- | --------------------------- |
| Image | `png`, `jpg`, `jpeg`, `gif` |
| Video | `mp4`                       |

### Example

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

### Response

```json theme={null}
{ "id": "media_xyz789", "url": "https://your-instance.com/uploads/image.png" }
```

<ResponseField name="id" type="string">
  The unique identifier for the uploaded file. Pass this value in the `image` array when creating a post.
</ResponseField>

<ResponseField name="url" type="string">
  The publicly accessible URL of the uploaded file.
</ResponseField>

### Using the uploaded media in a post

After uploading, reference the returned `id` in the `image` array of your post content:

```bash theme={null}
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"]
          }
        ]
      }
    ]
  }'
```

<Note>
  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](/sdk/reference) for details.
</Note>

<Warning>
  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.
</Warning>