Files Endpoints
List, inspect, update metadata, and delete files via the REST API.
The files endpoints let you query and manage files stored in UploadKit. All endpoints are scoped to the project associated with your API key.
File Object
All endpoints return the same file object shape:
{
"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",
"updatedAt": "2026-04-08T12:00:05.000Z"
}Status values:
| Status | Description |
|---|---|
UPLOADING | Presigned URL issued, PUT not yet confirmed |
UPLOADED | File confirmed and available at CDN URL |
FAILED | Upload confirmation failed (R2 object not found) |
DELETED | File deleted from storage (soft-deleted record) |
GET /api/v1/files
List files in the current project, ordered by creation date descending. Deleted files are excluded.
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Results per page (1–100) |
cursor | string | — | Pagination cursor from previous response |
curl example:
curl "https://api.uploadkit.dev/api/v1/files?limit=20" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx"Response:
{
"files": [
{
"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",
"createdAt": "2026-04-08T12:00:00.000Z"
}
],
"nextCursor": "65f1a2b3c4d5e6f7a8b9c0d1",
"hasMore": true
}To paginate, pass the nextCursor value as cursor on the next request:
curl "https://api.uploadkit.dev/api/v1/files?cursor=65f1a2b3c4d5e6f7a8b9c0d1" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx"When hasMore is false, nextCursor is null and you have reached the end.
GET /api/v1/files/:key
Retrieve a single file by its storage key. The key contains slashes and must be URL-encoded.
Path parameters:
| Parameter | Description |
|---|---|
key | URL-encoded file key (e.g., 65f0...%2FimageUploader%2Fabc123...%2Fphoto.jpg) |
curl example:
curl "https://api.uploadkit.dev/api/v1/files/65f0...%2FimageUploader%2Fabc123...%2Fphoto.jpg" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx"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",
"updatedAt": "2026-04-08T12:00:05.000Z"
}
}Error cases:
| Code | HTTP | Cause |
|---|---|---|
NOT_FOUND | 404 | No file with that key exists in the current project |
PATCH /api/v1/files/:key
Replace a file's metadata. The metadata object is written as-is — it does not merge with existing metadata.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
metadata | object | Yes | Key-value pairs to store as the file's metadata |
curl example:
curl -X PATCH "https://api.uploadkit.dev/api/v1/files/65f0...%2FimageUploader%2Fabc123...%2Fphoto.jpg" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"category": "avatar",
"approved": true
}
}'Response: { "file": { ... } } with the updated file object.
DELETE /api/v1/files/:key
Permanently delete a file from Cloudflare R2 and soft-delete its database record. Also decrements the project's storage usage counter for the current period.
Deletion is permanent. The file is removed from storage and the CDN URL stops resolving immediately.
curl example:
curl -X DELETE "https://api.uploadkit.dev/api/v1/files/65f0...%2FimageUploader%2Fabc123...%2Fphoto.jpg" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx"Response:
{ "ok": true }Error cases:
| Code | HTTP | Cause |
|---|---|---|
NOT_FOUND | 404 | File does not exist, already deleted, or belongs to a different project |
DELETE /api/v1/files
Bulk delete files from Cloudflare R2 and soft-delete their database records in a single request. Use this endpoint when deleting several files from your app so you do not spend one rate-limit point per file.
Deletes are scoped to the project associated with the API key. Keys that do not exist, are already deleted, or belong to another project are reported in failures.
| Field | Type | Required | Description |
|---|---|---|---|
keys | string[] | Yes | Storage keys to delete. Accepts 1–100 keys per request. |
curl example:
curl -X DELETE "https://api.uploadkit.dev/api/v1/files" \
-H "Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"keys": [
"65f0.../imageUploader/abc123.../photo.jpg",
"65f0.../imageUploader/def456.../avatar.webp"
]
}'Response:
{
"deleted": 2,
"failed": 0,
"failures": [],
"reclaimedBytes": 481920
}If only some files delete successfully, the API returns 207 Multi-Status with per-key failures:
{
"deleted": 1,
"failed": 1,
"failures": [
{
"key": "other-project/photo.jpg",
"code": "NOT_FOUND",
"message": "File does not exist, is already deleted, or belongs to a different project"
}
],
"reclaimedBytes": 240960
}