{{define "api.html"}}{{template "base" .}}{{end}} {{define "content"}}

Developer docs

Warpbox API

Anonymous uploads for curl, scripts, and ShareX. The upload endpoint accepts multipart files and returns either plain text or JSON based on the Accept header.

Curl upload

Without a JSON Accept header, Warpbox prints one plain box URL for shell-friendly usage.

curl -F file=@./report.pdf {{.Data.UploadURL}}

For automation, request JSON to get file URLs and the private manage/delete URLs.

curl -F file=@./report.pdf \
  -H 'Accept: application/json' \
  {{.Data.UploadURL}}

JSON response

The raw delete token is returned only once inside manageUrl and deleteUrl. Keep those links private. On error the body is { "error": "message" } with a non-2xx status (e.g. rate limited or over a limit).

{
  "boxId": "abc123",
  "boxUrl": "{{.Data.BaseURL}}/d/abc123",
  "zipUrl": "{{.Data.BaseURL}}/d/abc123/zip",
  "thumbnailUrl": "{{.Data.BaseURL}}/d/abc123/thumb/file123",
  "manageUrl": "{{.Data.BaseURL}}/d/abc123/manage/private-token",
  "deleteUrl": "{{.Data.BaseURL}}/d/abc123/manage/private-token/delete",
  "expiresAt": "2026-06-05T12:00:00Z",
  "files": [
    {
      "id": "file123",
      "name": "report.pdf",
      "size": "2.4 MiB",
      "url": "{{.Data.BaseURL}}/d/abc123/f/file123",
      "thumbnailUrl": "{{.Data.BaseURL}}/d/abc123/thumb/file123"
    }
  ]
}

ShareX setup

Import the uploader, then add your API key to upload as your account — with your account's size, daily, and retention limits — instead of as an anonymous guest.

1 · Import the uploader

  1. Download warpbox-anonymous.sxcu.
  2. In ShareX: Destinations → Custom uploader settings → Import → From file, then pick the .sxcu.

2 · Add your API key (upload as your account)

  1. Create a personal access token under Account → Access tokens and copy it.
  2. In Custom uploader settings, select the Warpbox uploader and open the Headers section.
  3. Add a header — Name Authorization, Value Bearer <your token>.

Without that header, uploads stay anonymous. With it, they're attributed to your account and use your account's limits.

{
  "Version": "1.0.0",
  "Name": "Warpbox (my account)",
  "DestinationType": "ImageUploader, FileUploader, TextUploader",
  "RequestMethod": "POST",
  "RequestURL": "{{.Data.ShareXExampleURL}}",
  "Headers": {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_TOKEN",
    "X-Warpbox-Batch": "sharex"
  },
  "Body": "MultipartFormData",
  "FileFormName": "{{.Data.ShareXFileFieldName}}",
  "URL": "{json:boxUrl}",
  "ThumbnailURL": "{json:thumbnailUrl}",
  "DeletionURL": "{json:deleteUrl}",
  "ErrorMessage": "{json:error}"
}

Grouping multiple files into one box

Grouping is opt-in via the X-Warpbox-Batch request header — without it, every file becomes its own box (the default). When the header is present, uploads sharing the same value (per account, or per IP for anonymous) within {{.Data.ShareXGroupWindow}} of each other are added to the same box, so a multi-file ShareX selection produces one shareable link instead of one per file. The shipped config sets X-Warpbox-Batch: sharex; remove that header for one box per file.

The response also exposes {json:thumbnailUrl} for ShareX previews, {json:deleteUrl} for the deletion URL, and {json:error} so ShareX surfaces messages like rate limiting.

Multipart fields

file

One or more files for curl, browser, and generic multipart clients.

sharex

One or more files from ShareX custom uploader configs.

max_days

Optional number of days before expiration. Defaults to 7.

expires_minutes

Optional lifetime in minutes. Takes precedence over max_days when greater than zero — useful for sub-day expiries (e.g. 60 for one hour).

max_downloads

Optional download count limit.

password

Optional password required before viewing/downloading.

obfuscate_metadata

Optional on; hides names/counts until unlock when a password is set.

{{end}}