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).
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.status); } } Property Type Description codestringMachine-readable error code (e.g. 'FILE_TOO_LARGE', 'INVALID_FILE_TYPE', 'UNAUTHORIZED'). messagestringHuman-readable error description. statusnumberHTTP 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.1.0'