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 in the x-api-key header:

curl https://api.uploadkit.dev/api/v1/files \
  -H "x-api-key: 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 return the requested resource directly:

{
  "id": "abc123",
  "key": "uploads/abc123/photo.jpg",
  "url": "https://cdn.uploadkit.dev/uploads/abc123/photo.jpg",
  "status": "UPLOADED"
}

Error responses always have the shape:

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size 6291456 bytes exceeds the 4194304 byte limit",
    "suggestion": "Upgrade your plan at app.uploadkit.dev/billing"
  }
}

See Error Codes for the complete list.

Rate Limiting

The API uses a sliding window rate limiter backed by Upstash Redis. Limits are per API key:

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

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 23

Pagination

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

Query parameters:

Response shape:

{
  "items": [...],
  "nextCursor": "eyJpZCI6ImFiYzEyMyJ9",
  "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.

Endpoints