Public API Reference

🔐 Authentication

File uploads and short-link creation support anonymous use for one day, one week and one month. No API key is required for those durations.

An authenticated request may include Authorization: Bearer <access-token> to associate the result with the account. The 12m file duration and TWELVE_MONTHS short-link validity require an authenticated account.

Never place access tokens, upload tokens or deletion URLs in logs, analytics, source code or public messages.

📁 Supported files and size limits

• Images: .jpg, .jpeg, .png, .gif, .webp
• Videos: .mp4, .webm
• Archives: .zip, .7z, .gz, .rar

The filename extension, declared media type and actual file content must agree. Renaming an unsupported file does not make it valid.

The simple endpoint has a 99 MiB hard limit. Switching at 90 MiB provides a stable client boundary.

📤 Simple file upload

POST/api/upload

Send multipart/form-data with these fields:

• file — required binary file.
• storage_duration — one of 1d, 1w, 1m or 12m.

curl https://api.selfgonefile.com/api/upload \
  -F "file=@./example.png" \
  -F "storage_duration=1w"

An authenticated twelve-month request also adds:

-H "Authorization: Bearer <access-token>"

🧩 Multipart file upload

Use this flow for files larger than 90 MiB. A successful session must be completed explicitly.

1. POST/api/uploads/multipart

   Send JSON containing filename, integer sizeBytes, declaredMime and duration.

   {
     "filename": "example.mp4",
     "sizeBytes": 125829120,
     "declaredMime": "video/mp4",
     "duration": "1w"
   }

2. PUT/api/uploads/multipart/{uploadId}/parts/{partNumber}

   Send each part as application/octet-stream, starting at part 1. Include the exact Content-Length, X-Upload-Token and lowercase hexadecimal X-Part-SHA256.

3. GET/api/uploads/multipart/{uploadId}

   Include X-Upload-Token to retrieve confirmed part numbers before resuming.

4. POST/api/uploads/multipart/{uploadId}/complete

   Include X-Upload-Token. Complete only after every part has been confirmed.

5. DELETE/api/uploads/multipart/{uploadId}

   Include X-Upload-Token to cancel an unfinished session.

The initiation response provides uploadId, uploadToken, partSizeBytes, totalParts and expiresAt. Follow those returned values exactly. Do not invent part sizes or persist the upload token beyond the active session.

📨 Successful file response

Simple upload and multipart completion return the same public result:

{
  "id": "aB3dE7x",
  "file": "https://api.selfgonefile.com/api/v/aB3dE7x.png",
  "viewfile": "https://selfgonefile.com/view/aB3dE7x.png",
  "thumbnail": "https://api.selfgonefile.com/api/v/aB3dE7x/thumb",
  "delete": "https://api.selfgonefile.com/api/v/aB3dE7x/delete?token=<deletion-token>"
}

• viewfile is the shareable viewer page.
• file is the direct file URL.
• thumbnail is null for archives.
• delete is a secret capability URL. Anyone holding it can delete the resource.

🔗 Create a short link

POST/api/short-links

Send application/json:

{
  "destinationUrl": "https://example.com/article",
  "validity": "ONE_WEEK",
  "captchaRequired": false,
  "password": "optional-password"
}

• destinationUrl must be an absolute public HTTP or HTTPS URL, no longer than 2048 characters.
• validity accepts ONE_DAY, ONE_WEEK, ONE_MONTH or authenticated-only TWELVE_MONTHS.
• captchaRequired is required and must be a boolean.
• password is optional; when present it must contain 8–128 characters.
• A SelfGoneFile short URL cannot be shortened again.

{
  "success": true,
  "shortLink": {
    "id": "3fa09bc",
    "shortUrl": "https://selfgonefile.com/s/3fa09bc",
    "expiresAt": "2026-09-04T12:00:00.000Z",
    "passwordRequired": true,
    "captchaRequired": false
  }
}

Share the returned shortUrl. When protection is enabled, the public page requests the required verification before redirecting.

🛡️ Limits, retries and errors

• New upload requests are rate limited per client. Current responses include standard RateLimit-* headers; treat those headers as authoritative.
• At most three unfinished multipart sessions may be active per client or account.
• Retry network failures, 408, 429 and 5xx responses only. Respect Retry-After and use bounded retries.
• Do not retry other 4xx responses without correcting the request.

📬 Support

Questions about the public contract: [email protected]