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

# Upload media

> Transfer files to storage, validate them, then attach their IDs.

## Supported source files

| Media | Formats | Maximum size |
| - | - | - |
| Image | JPEG, PNG | 8 MiB |
| Video | MP4, MOV | 1 GiB |

File contents are validated after upload. Platform publishing rules may impose additional duration, codec, attachment, and caption requirements.

## CLI and MCP

```bash theme={null}
postinger upload ./photo.jpg
```

The CLI handles transfer and validation and returns ready media. Hosted MCP's `upload_media` accepts a publicly accessible HTTPS URL. It cannot read a local path. Local stdio MCP can accept a file inside its configured media root.

## HTTP upload

1. Call `POST /media/uploads` with `filename`, `contentType`, and `sizeBytes`.
2. For a single upload, PUT the raw file bytes to `data.uploadUrl` with the matching `Content-Type`.
3. Call `POST /media/MEDIA_ID/complete` to validate the uploaded file.
4. Use the ready media ID in the post's `mediaIds` array.

Never attach the Postinger Authorization header to the signed storage URL. That URL already authorizes the upload.

```bash theme={null}
curl --fail-with-body "$POSTINGER_API_URL/public/v1/media/uploads" \
  -H "Authorization: Bearer $POSTINGER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filename":"photo.jpg","contentType":"image/jpeg","sizeBytes":12345}'
```

Replace `12345` with the actual file size. Set `UPLOAD_URL` to the returned URL, then upload and complete:

```bash theme={null}
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/jpeg' --upload-file ./photo.jpg
curl --fail-with-body -X POST \
  "$POSTINGER_API_URL/public/v1/media/MEDIA_ID/complete" \
  -H "Authorization: Bearer $POSTINGER_API_KEY"
```

## Multipart video uploads

When `multipart` is true, `uploadUrl` is empty. Split the file using the returned `partSize`. Call `/media/MEDIA_ID/multipart` with `operation: "sign"` and a one-based `partNumber` for each part, then PUT its bytes to the returned URL. Use `operation: "list"` to inspect uploaded parts and `operation: "complete"` to assemble them. Finally call `/media/MEDIA_ID/complete` to validate the complete file.

`operation: "abort"` cancels an unfinished multipart upload. If an upload result is uncertain, inspect the reported media ID before creating another reservation.


## Related topics

- [Local MCP server](/mcp/local-server.md)
- [MCP tool reference](/mcp/tools.md)
- [Publish a post](/guides/publishing.md)
- [MCP examples](/mcp/examples.md)
- [Create an image or video upload](/api-reference/media/create-an-image-or-video-upload.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.