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

# Upload File(s)

Upload between 1 and 9 files in a single request. Every upload automatically creates a post. When sending multiple files, they are grouped into an album by default.

## Headers

| Header             | Required | Description                                                                                                                                             |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api-key`          | Yes      | Your API key                                                                                                                                            |
| `post-privacy`     | No       | `public`, `unlisted`, or `private` (default)                                                                                                            |
| `post-title`       | No       | Post title, max 30 characters                                                                                                                           |
| `post-description` | No       | Post description, max 200 characters                                                                                                                    |
| `post-type`        | No       | `album` (default) or `individual`. Only applies to two or more files.                                                                                   |
| `include-metadata` | No       | `true` to keep file metadata. Omitted or `false` strips it (default).                                                                                   |
| `priority`         | No       | `false` to opt video uploads out of priority (adaptive) streaming. Omitted or `true` keeps it on (default), subject to your remaining priority minutes. |

## Behavior

* **One file:** creates a single post. `post-type` is ignored.
* **Two or more files, no header or `album`:** creates one album post containing all files.
* **Two or more files, `individual`:** creates a separate post for each file.
* **`post-privacy: private`:** the returned `url` (and any `urls` in albums) is a signed URL with a 24-hour expiry. After it expires, call [`GET /posts/{code}`](/api-reference/endpoint/post) or [`GET /uploads`](/api-reference/endpoint/uploads) to get a fresh signed URL.
* **Video uploads:** `.mp4`, `.mov`, and `.mkv` files are remuxed to MP4 with `+faststart` so the browser can begin playback before the full file has downloaded. `.mov` and `.mkv` uploads are stored (and returned) with an `.mp4` extension. If remuxing fails, the original file is stored unchanged. See [File Types](/concepts/file-types) for details.
* **Metadata:** Metadata (camera, GPS location, timestamp) is stripped by default. For images, EXIF is removed from PNG, JPG, and WebP up to 100 MB (larger images are stored unchanged). For videos, container metadata is removed during the MP4 remux. Send `include-metadata: true` to keep it.
* **Priority streaming:** Eligible videos are streamed with adaptive bitrate by default, spending [priority minutes](/concepts/plans). Send `priority: false` to upload in standard quality instead and save your minutes. The post's `priority` field reflects whether the video ended up on adaptive streaming.

## Examples

Upload a single file:

```bash theme={null}
curl -X POST "https://api.snipp.gg/upload" \
  -H "api-key: YOUR_API_KEY" \
  -H "post-privacy: unlisted" \
  -H "post-title: my gaming POV" \
  -F "file=@screenshot.png"
```

Upload an album (two or more files default to album):

```bash theme={null}
curl -X POST "https://api.snipp.gg/upload" \
  -H "api-key: YOUR_API_KEY" \
  -H "post-privacy: public" \
  -H "post-title: Game Moderation Evidence" \
  -F "file=@photo1.png" \
  -F "file=@photo2.png" \
  -F "file=@photo3.png"
```

Upload multiple files as individual posts:

```bash theme={null}
curl -X POST "https://api.snipp.gg/upload" \
  -H "api-key: YOUR_API_KEY" \
  -H "post-type: individual" \
  -F "file=@image1.png" \
  -F "file=@image2.png"
```

## Responses

Single file:

```json theme={null}
{
  "message": "Upload successful!",
  "url": "https://i.snipp.gg/123456789012345678/a1b2c3d4e5f6789012345678abcdef01.png",
  "file": {
    "size": 2487312,
    "size_formatted": "2.37 MB",
    "mime_type": "image/png",
    "dimensions": { "width": 1920, "height": 1080 }
  },
  "processing_time": 412,
  "post": {
    "code": "AbCd1234",
    "url": "https://snipp.gg/p/AbCd1234",
    "postPrivacy": "unlisted",
    "priority": false
  }
}
```

`priority` is `true` when the upload is a video that was placed on priority (adaptive) streaming, and `false` otherwise.

Album (two or more files, default): one `post` containing every file.

```json theme={null}
{
  "message": "Upload successful!",
  "files": [
    {
      "index": 0,
      "url": "https://i.snipp.gg/123456789012345678/a1b2c3d4e5f6789012345678abcdef01.png",
      "size": 2487312,
      "size_formatted": "2.37 MB",
      "mime_type": "image/png",
      "status": "success",
      "dimensions": { "width": 1920, "height": 1080 }
    },
    {
      "index": 1,
      "url": "https://i.snipp.gg/123456789012345678/b2c3d4e5f6789012345678abcdef0102.png",
      "size": 1840221,
      "size_formatted": "1.76 MB",
      "mime_type": "image/png",
      "status": "success",
      "dimensions": { "width": 1280, "height": 720 }
    }
  ],
  "processing_time": 938,
  "post": {
    "code": "AbCd1234",
    "url": "https://snipp.gg/p/AbCd1234",
    "postPrivacy": "public",
    "isAlbum": true,
    "fileCount": 2,
    "priority": false
  }
}
```

Individual (`post-type: individual`): one entry in `post.posts` per file. If a file fails, a `failed` array is included alongside `files`.

```json theme={null}
{
  "message": "Upload successful!",
  "files": [
    {
      "index": 0,
      "url": "https://i.snipp.gg/123456789012345678/a1b2c3d4e5f6789012345678abcdef01.png",
      "size": 2487312,
      "size_formatted": "2.37 MB",
      "mime_type": "image/png",
      "status": "success"
    }
  ],
  "failed": [
    {
      "index": 1,
      "error": "Weekly usage limit exceeded.",
      "status": "failed"
    }
  ],
  "processing_time": 938,
  "post": {
    "posts": [
      {
        "code": "AbCd1234",
        "url": "https://snipp.gg/p/AbCd1234",
        "postPrivacy": "public",
        "priority": false
      }
    ]
  }
}
```