API Reference Complete API reference for @uploadkitdev/core — all types, methods, and error codes.
Factory function. Creates and returns an UploadKitClient.
function createUploadKit ( config : UploadKitConfig ) : UploadKitClient Property Type Required Default Description apiKeystringYes — API key prefixed uk_live_ or uk_test_. baseUrlstringNo 'https://api.uploadkit.dev'Override the API endpoint. maxRetriesnumberNo 3Retry attempts on transient failures. 0 disables retries.
The main SDK client. Created by createUploadKit().
Method Signature Description upload(options: UploadOptions) => Promise<UploadResult>Upload a file. Automatically uses multipart for files >10 MB. listFiles(options?: ListFilesOptions) => Promise<ListFilesResult>List files for this API key's project. deleteFile(key: string) => Promise<void>Permanently delete a file by its storage key.
client. upload (options: UploadOptions): Promise < UploadResult > Property Type Required Description fileFileYes The file to upload. routestringYes Route name from your server-side file router. metadataRecord<string, unknown>No JSON-serializable metadata forwarded to onUploadComplete. onProgress(percentage: number) => voidNo Called with progress percentage (0–100). signalAbortSignalNo Cancellation signal from AbortController.
Property Type Description idstringUploadKit file ID. keystringStorage key (e.g. 'imageUploader/abc123/photo.jpg'). Use for deletion. namestringOriginal filename. sizenumberFile size in bytes. typestringMIME type (e.g. 'image/jpeg'). urlstringCDN URL for the file. statusstringUpload status — 'completed' on success. metadataRecord<string, unknown>Metadata returned from onUploadComplete, if any. createdAtstringISO 8601 timestamp.
client. listFiles (options ?: ListFilesOptions): Promise < ListFilesResult > Property Type Default Description limitnumber20Maximum number of files to return (1–100). cursorstring— Pagination cursor from a previous response's nextCursor.
Property Type Description filesUploadResult[]Array of file records for the current page. nextCursorstring | undefinedPass as cursor in the next call to get the next page. undefined means no more pages.
client. deleteFile (key: string): Promise <void> Permanently deletes the file with the given storage key. Returns Promise<void> on success. Throws UploadKitError on failure (including 404 if the file does not exist).
client. deleteFiles (keys: string[]): Promise < DeleteFilesResult > Permanently deletes multiple files by storage key in one API request. Accepts 1–100 keys. Use this for bulk cleanup instead of calling deleteFile() repeatedly.
Property Type Description deletednumberNumber of files deleted from storage and soft-deleted in UploadKit. failednumberNumber of keys that could not be deleted. reclaimedBytesnumberTotal storage bytes reclaimed by successful deletes. failures{ key: string; code: string; message: string }[]Per-key failure details.
Thrown by all client methods on API or network errors. Import from @uploadkitdev/core.
import { UploadKitError } from '@uploadkitdev/core' ; try { await client. upload ({ file, route: 'imageUploader' }); } catch (err) { if (err instanceof UploadKitError ) { console. error (err.code, err.message, err.statusCode); } } Property Type Description codestringMachine-readable error code (e.g. 'FILE_TOO_LARGE', 'INVALID_FILE_TYPE', 'UNAUTHORIZED'). messagestringHuman-readable error description. statusCodenumberHTTP status code from the API. suggestionstringActionable hint for resolving the error.
Code Status When it occurs MISSING_API_KEY400 createUploadKit() called without apiKey.UNAUTHORIZED401 Invalid or revoked API key. FILE_TOO_LARGE413 File exceeds the route's maxFileSize. INVALID_FILE_TYPE415 MIME type not in the route's allowedTypes. ROUTE_NOT_FOUND404 Route name does not exist in your file router. UPLOAD_FAILED500 Unexpected error during upload.
These types are exported for advanced use cases (custom wrappers, testing). The SDK does not rely on them being stable.
Internal response from POST /api/v1/upload/request (single-part upload).
Property Type Description fileIdstringID of the pending file record. uploadUrlstringPresigned PUT URL for direct-to-storage upload. keystringStorage key for the file. cdnUrlstringCDN URL that will serve the file after upload.
Internal response from POST /api/v1/upload/multipart/init (files >10 MB).
Property Type Description fileIdstringID of the pending file record. uploadIdstringMultipart upload ID (from R2/S3). keystringStorage key for the file. partsArray<{ partNumber: number; uploadUrl: string }>Array of presigned PUT URLs, one per part.
import { VERSION } from '@uploadkitdev/core' ; // '0.2.1'