API Documentation

Overview

The Uploadex API lets you programmatically upload files, list them, and update metadata on behalf of the API key's owner. Every endpoint is a REST resource: JSON (or multipart for binary uploads) in, JSON out, HTTPS only.

Base URL: https://uploadex.net/api/v1
Auth: Bearer tokens in the Authorization header
Transport: HTTPS only · TLS 1.2 or 1.3
Encoding: UTF-8 JSON · multipart/form-data for uploads
Dates: ISO 8601 in UTC · 2026-04-21T08:12:04Z

Authentication

Every request must include an Authorization header with a Bearer token. Create and rotate keys from your developer dashboard.

Authorization: Bearer ux_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys begin with ux_live_. They are shown exactly once on creation — store them in a secret manager. Keys can be scoped to specific actions (files:read, files:write, upload, or *) and set to expire at a future date.

API access requires a plan with API access enabled. If the account downgrades to a plan without API access, existing keys stop working until the account re-upgrades. Revoke leaked keys immediately from the developer dashboard.

Quickstart

Fetch your account info to confirm the key works.

# Get your account info
curl https://uploadex.net/api/v1/account \
  -H "Authorization: Bearer $UX_API_KEY"

Response · 200 OK

{
  "data": {
    "id":               "clxxxxxxxxxxxxxxxxxxxxxx",
    "email":            "[email protected]",
    "name":             "Your Name",
    "plan":             "PRO",
    "balance":          0,
    "totalEarnings":    0,
    "storageUsed":      52428800,
    "storageLimit":     53687091200,
    "storageFormatted": "50 MB / 50 GB",
    "fileCount":        3,
    "createdAt":        "2026-04-01T09:21:00.000Z"
  }
}

Plan limits

Upload and storage limits are plan-driven and can change when the account upgrades or downgrades. Limits for plans that include API access:

Plan	Max file size	Storage
Pro	10 GB	100 GB
Business	50 GB	1 TB
Business Plus	100 GB	5 TB

Rate limits

Rate limits protect the service from runaway traffic. Exceeding a limit returns 429 Too Many Requests.

Scope	Limit	Window	Subject
Upload init	30	1 min	per API key
Download	60	1 min	per IP
Login	10	15 min	per IP
Register	5	1h	per IP

Errors

Error responses use standard HTTP status codes and a consistent JSON body.

{ "error": "Invalid or missing API key" }

Status	Meaning
400	The request body was malformed or failed validation.
401	Missing or invalid API key.
403	The key is missing a required scope (e.g. files:write).
404	The resource does not exist or does not belong to the key owner.
413	The file exceeds the account's plan file-size limit.
429	Rate limit exceeded. Slow down and retry.
500	Internal error. Check the status page before retrying.

Pagination

List endpoints use page-based pagination. Pass page (1-indexed) and limit (max 100) as query parameters.

GET /api/v1/files?page=1&limit=50

Account

GET/api/v1/account

Return account info, plan, storage usage, file count.

Scope: no scope required beyond a valid key.

Upload

POST/api/v1/upload

Initiate a multipart upload. Returns presigned URLs the client uses to PUT chunks to R2 object storage.

Field	Type	Description
filename	string · required	File name, including extension (max 255 chars).
size	integer · required	Total file size in bytes.
contentType	string · required	MIME type (max 200 chars).

Scope: upload. Returns 413 if size exceeds the account's plan limit.

Files

GET/api/v1/files

List files owned by the key. Supports page, limit (max 100), status.

GET/api/v1/files/:id

Retrieve a single file by ID.

PATCH/api/v1/files/:id

Update displayName, description, tags, or visibility.

DELETE/api/v1/files/:id

Delete the file and reclaim storage quota.

{
  "data": {
    "id":            "clxxxxxxxxxxxxxxxxxxxxxx",
    "slug":          "9nK2xA",
    "filename":      "demo.mp4",
    "size":          881975296,
    "sizeFormatted": "841.1 MB",
    "mimeType":      "video/mp4",
    "status":        "READY",
    "scanStatus":    "CLEAN",
    "downloads":     128,
    "views":         412,
    "tags":          ["demo"],
    "visibility":    "PUBLIC",
    "adsEnabled":    true,
    "createdAt":     "2026-04-21T08:12:04.000Z",
    "updatedAt":     "2026-04-21T08:12:04.000Z"
  }
}

Scopes: GET requires files:read; PATCH/DELETE require files:write.

Uploadex API reference.