REST API Overview

The UploadKit REST API gives backend developers and non-JavaScript consumers direct access to the upload flow, file management, project administration, and webhook configuration — all without the SDK.

Base URL

https://api.uploadkit.dev/api/v1

All requests must be made over HTTPS. HTTP requests are rejected.

Authentication

Every request requires an API key passed as a Bearer token in the Authorization header:

curl https://api.uploadkit.dev/api/v1/files \
  -H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx"

API keys come in two forms:

See Authentication for full details on key types and security.

Response Format

All responses are JSON. Successful responses are typically wrapped in a resource envelope — the exact key depends on the endpoint (file, files, project, projects, router, routers, keys, usage, logs, etc.). Simple acknowledgements return { "ok": true }.

Example — single-file response:

{
  "file": {
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "key": "65f0.../imageUploader/abc123.../photo.jpg",
    "name": "photo.jpg",
    "size": 204800,
    "type": "image/jpeg",
    "url": "https://cdn.uploadkit.dev/65f0.../imageUploader/abc123.../photo.jpg",
    "status": "UPLOADED",
    "metadata": { "userId": "user_123" },
    "createdAt": "2026-04-08T12:00:00.000Z"
  }
}

Error responses always follow this shape:

{
  "error": {
    "type": "invalid_request",
    "code": "TIER_LIMIT_EXCEEDED",
    "message": "You have exceeded your file size limit",
    "suggestion": "Upgrade your plan at app.uploadkit.dev/billing"
  }
}

See Error Codes for the complete list.

Rate Limiting

The API enforces per-API-key rate limits in a fixed 60-second window, backed by Redis with an in-memory fallback:

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 23 seconds"
  }
}

The retry delay is embedded in the error message. The SDK parses this automatically and retries with exponential backoff.

Pagination

List endpoints use cursor-based pagination for consistent results even when records are added or deleted between requests.

Query parameters:

Response shape (files):

{
  "files": [...],
  "nextCursor": "65f1a2b3c4d5e6f7a8b9c0d1",
  "hasMore": true
}

Pass nextCursor as cursor on the next request to get the following page. When hasMore is false, you have reached the last page and nextCursor is null.

Endpoints