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

Endpoints

Upload
POST /api/v1/upload
Resumable create
POST /api/v1/uploads/resumable
Resumable status
GET /api/v1/uploads/resumable/{sessionID}
Resumable chunk
PUT /api/v1/uploads/resumable/{sessionID}/files/{fileID}/chunks/{index}
Resumable complete
POST /api/v1/uploads/resumable/{sessionID}/complete
Health
GET /health

Resumable uploads

Browser uploads use the resumable API by default. Custom clients can use the same flow: create a session with file metadata, upload exact-sized chunks, then complete the session. Chunks are temporary and are cleaned if the session expires.

# 1. Create a session.
curl -s {{.Data.BaseURL}}/api/v1/uploads/resumable \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"name":"report.pdf","size":1048576,"contentType":"application/pdf"}],"expiresMinutes":1440}'

# 2. Upload each chunk using the returned sessionId, file id, and chunkSize.
dd if=./report.pdf bs=8388608 count=1 skip=0 2>/dev/null | \
  curl -X PUT --data-binary @- \
  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/files/FILE_ID/chunks/0

# 3. Complete after all chunks are present. The response is the normal upload JSON.
curl -X POST -H 'Accept: application/json' \
  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/complete

For authenticated uploads, send the same Authorization: Bearer <token> header on every resumable request. Incomplete chunks are stored under data/tmp/uploads before finalizing into the selected storage backend.

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}}