API

Everything the site does can be done over HTTP. Responses are JSON. The examples use .

Authentication

Generate a token on Account and send it with every request:

Authorization: Bearer YOUR_TOKEN

A token can do anything your account can, including admin actions if you're an admin. Make a separate, named token for each device or app, so you can revoke one without breaking the others. Keep tokens out of web pages and public code.

Upload

POST /upload

A multipart/form-data body with up to 10 files in fields named files[]. Compatible with pomf and uguu clients.

• expires (query, optional): hours until deletion, or never if your account allows it. Defaults to your default expiry.
• output (query, optional): text returns just the links, one per line.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files[]=@photo.png" -F "files[]=@notes.txt" \
  "/upload?expires=24"

{
  "success": true,
  "files": [
    {
      "filename": "k3x9a1bq.png",
      "name": "photo.png",
      "size": 48213,
      "hash": "2fd4e1c6…",
      "url": "https://f.davidxie.dev/k3x9a1bq.png",
      "expires": 1793708415000
    }
  ]
}

expires is a Unix time in milliseconds, or null for files that never expire. If any file in a request fails, none of them are kept, and the response is {"success": false, "errorcode": 413, "description": "…"}.

Your account

GET /api/me

Your username, whether you're an admin, and your limits: maxBytes, defaultHours, maxHours and the expiryOptions you can pick from. Hours can be "never".

GET /api/me/tokens

Your tokens: id, name, created and lastUsed. The tokens themselves are never shown again.

POST /api/me/tokens

Make a token: {"name": "ShareX laptop"}. The response includes token, the only time you'll see it.

DELETE /api/me/tokens/{id}

Revoke one token.

Your files

GET /api/uploads

Your files, newest first: key, name, size, url, created and expires. The owner can add ?all=1 for everyone's, or ?user=name for one person's.

GET /api/uploads/{key}

One file. key is the file's name in its link, like k3x9a1bq.png.

PATCH /api/uploads/{key}

Change how long a file lasts, counted from now, within your limits.

curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"expires": "never"}' \
  /api/uploads/k3x9a1bq.png

DELETE /api/uploads/{key}

Delete a file. Its link stops working straight away.

Errors

Failed requests return {"error": "…"} with a status code:

• 400 something in the request is invalid, like an expiry over your limit
• 401 missing, wrong or revoked token
• 403 admins only
• 404 no such file, or it isn't yours
• 413 file larger than your limit
• 415 request body isn't JSON where JSON is expected
• 429 too many failed logins; wait a few minutes

Hosting HTML

Files are served from a separate domain from this site, so uploaded HTML pages work fully, scripts included, while having no access to your account. Every file gets its own random name, so a page works best as a single file with its CSS and JavaScript inline, or linking to other uploads by their full URLs. Set expires=never to keep a page up.

Admin and owner

Admins can use:

• GET /api/admin/overview counts, storage and site settings
• PUT /api/settings {"maxMb", "defaultHours", "maxHours"}
• POST /api/users {"name"}, returns a generated password
• GET /api/invites invite codes, with uses left and who used them
• POST /api/invites {"uses": 1, "days": 7}, returns the code (leave out days for no expiry)
• DELETE /api/invites/{id} revoke a code

Anyone with a code can sign up with POST /api/signup {"code", "username", "password"}, which also logs them in.

Everything that touches other people's accounts or files is for the owner only:

• GET /api/users all accounts with their limits
• GET /api/users/{name} one account
• POST /api/users with "admin": true to create an admin
• POST /api/users/{name}/limits {"maxMb", "defaultHours", "maxHours"}, blank for the site's
• POST /api/users/{name}/reset new generated password
• POST /api/users/{name}/admin {"admin": true}
• POST /api/users/{name}/logout end all their sessions
• POST /api/users/{name}/revoke-token revoke all their tokens
• DELETE /api/users/{name}/tokens?id={id} revoke one
• DELETE /api/users/{name}/uploads delete all their files
• DELETE /api/users/{name} delete the account and its files
• DELETE /api/uploads delete every file

ShareX

Account has a button that downloads a ready-made ShareX config with your token filled in.