Upload File(s)

Upload between 1 and 50 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
`relay-key`	Yes	Your Relay 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} or GET /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 file is rejected as corrupt or unplayable. See File Types for details.
Metadata: Metadata (camera, GPS location, timestamp) is stripped by default. For images, metadata is removed from PNG, JPG, WebP and GIF at any size, without re-encoding, so the pixels are untouched. Display orientation is preserved on JPG and WebP, and GIF animation and looping are preserved. 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. 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.
Failures: when every file in the request fails, the response is 400. For a single-file upload the reason is returned directly as error (for example Weekly usage limit exceeded.). For multi-file uploads the response is All files failed to upload. with a failed array naming each file by index.

Examples

Upload a single file:

curl -X POST "https://relay.snipp.gg/upload" \
  -H "relay-key: YOUR_RELAY_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):

curl -X POST "https://relay.snipp.gg/upload" \
  -H "relay-key: YOUR_RELAY_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:

curl -X POST "https://relay.snipp.gg/upload" \
  -H "relay-key: YOUR_RELAY_KEY" \
  -H "post-type: individual" \
  -F "file=@image1.png" \
  -F "file=@image2.png"

Responses

Single file:

{
  "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.

{
  "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 and the message counts what landed.

{
  "message": "1 of 2 files uploaded successfully.",
  "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
      }
    ]
  }
}

Overview

Uploads

Posts

Users

Notifications

Meta

Upload File(s)

Headers

Behavior

Examples

Responses

​Headers

​Behavior

​Examples

​Responses

Headers

Behavior

Examples

Responses