--- title: "Upload file V1" method: POST path: "/api/v1/files/upload" tags: ["Upload File"] --- # Upload file V1 `POST /api/v1/files/upload` ImageKit.io allows you to upload files directly from both the server and client sides. For server-side uploads, private API key authentication is used. For client-side uploads, generate a one-time `token`, `signature`, and `expire` from your secure backend using private API. [Learn more](/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload) about how to implement client-side file upload. The [V2 API](/docs/api-reference/upload-file/upload-file-v2) enhances security by verifying the entire payload using JWT. **File size limit** \ On the free plan, the maximum upload file sizes are 25MB for images, audio, and raw files and 100MB for videos. On the Lite paid plan, these limits increase to 40MB for images, audio, and raw files and 300MB for videos, whereas on the Pro paid plan, these limits increase to 50MB for images, audio, and raw files and 2GB for videos. These limits can be further increased with enterprise plans. **Version limit** \ A file can have a maximum of 100 versions. **Demo applications** - A full-fledged [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader), supporting file selections from local storage, URL, Dropbox, Google Drive, Instagram, and more. - [Quick start guides](/docs/quick-start-guides) for various frameworks and technologies. ## Response `200` File uploaded successfully. - Upload — Object containing details of a successful upload. - `fileId` string — Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file. - `name` string — Name of the asset. - `filePath` string — The relative path of the file in the media library e.g. `/marketing-assets/new-banner.jpg`. - `url` string — A publicly accessible URL of the file. - `thumbnailUrl` string — In the case of an image, a small thumbnail URL. - `height` number — Height of the image in pixels (Only for images) - `width` number — Width of the image in pixels (Only for Images) - `size` number — Size of the image file in Bytes. - `bitRate` integer — The bit rate of the video in kbps (only for video). - `duration` integer — The duration of the video in seconds (only for video). - `audioCodec` string — The audio codec used in the video (only for video). - `videoCodec` string — The video codec used in the video (only for video). - `tags` union — The array of tags associated with the asset. If no tags are set, it will be `null`. Send `tags` in `responseFields` in API request to get the value of this field. - string[] - string[] - `AITags` union — An array of tags assigned to the uploaded file by auto tagging. - AITag[] - `name` string — Name of the tag. - `confidence` number — Confidence score of the tag. - `source` string — Source of the tag. Possible values are `google-auto-tagging` and `aws-auto-tagging`. - AITag[] - `name` string — Name of the tag. - `confidence` number — Confidence score of the tag. - `source` string — Source of the tag. Possible values are `google-auto-tagging` and `aws-auto-tagging`. - `versionInfo` VersionInfo — An object containing the file or file version's `id` (versionId) and `name`. - `id` string — Unique identifier of the file version. - `name` string — Name of the file version. - `isPrivateFile` boolean — Is the file marked as private. It can be either `true` or `false`. Send `isPrivateFile` in `responseFields` in API request to get the value of this field. - `isPublished` boolean — Is the file published or in draft state. It can be either `true` or `false`. Send `isPublished` in `responseFields` in API request to get the value of this field. - `customCoordinates` union — Value of custom coordinates associated with the image in the format `x,y,width,height`. If `customCoordinates` are not defined, then it is `null`. Send `customCoordinates` in `responseFields` in API request to get the value of this field. - string - unknown - `fileType` string — Type of the uploaded file. Possible values are `image`, `non-image`. - `customMetadata` CustomMetadata — A key-value data associated with the asset. - `selectedFieldsSchema` SelectedFieldsSchema — This field is included in the response only if the Path policy feature is available in the plan. It contains schema definitions for the custom metadata fields selected for the specified file path. Field selection can only be done when the Path policy feature is enabled. Keys are the names of the custom metadata fields; the value object has details about the custom metadata schema. - `extensionStatus` object — Extension names with their processing status at the time of completion of the request. It could have one of the following status values: `success`: The extension has been successfully applied. `failed`: The extension has failed and will not be retried. `pending`: The extension will finish processing in some time. On completion, the final status (success / failed) will be sent to the `webhookUrl` provided. If no extension was requested, then this parameter is not returned. - `google-auto-tagging` 'success' | 'pending' | 'failed' - `aws-auto-tagging` 'success' | 'pending' | 'failed' - `remove-bg` 'success' | 'pending' | 'failed' - `ai-auto-description` 'success' | 'pending' | 'failed' - `ai-tasks` 'success' | 'pending' | 'failed' - `metadata` Metadata — JSON object containing metadata. - `height` integer — The height of the image or video in pixels. - `width` integer — The width of the image or video in pixels. - `size` integer — The file size in bytes. - `format` string — The format of the file (e.g., 'jpg', 'mp4'). - `hasColorProfile` boolean — Indicates if the image has a color profile. - `quality` integer — The quality indicator of the image. - `density` integer — The density of the image in DPI. - `hasTransparency` boolean — Indicates if the image contains transparent areas. - `pHash` string — Perceptual hash of the image. - `bitRate` integer — The bit rate of the video in kbps (only for video). - `duration` integer — The duration of the video in seconds (only for video). - `audioCodec` string — The audio codec used in the video (only for video). - `videoCodec` string — The video codec used in the video (only for video). - `exif` object - `image` ExifImage — Object containing EXIF image information. - `Make` string - `Model` string - `ImageDescription` string - `Artist` string - `Copyright` string - `Orientation` integer - `XResolution` number - `YResolution` number - `ResolutionUnit` integer - `Software` string - `ModifyDate` string - `YCbCrPositioning` integer - `ExifOffset` integer - `GPSInfo` integer - `thumbnail` Thumbnail — Object containing Thumbnail information. - `Compression` integer - `XResolution` number - `YResolution` number - `ResolutionUnit` integer - `ThumbnailOffset` integer - `ThumbnailLength` integer - `exif` ExifDetails — Object containing Exif details. - `ExposureTime` number - `FNumber` number - `ExposureProgram` integer - `ISO` integer - `ExifVersion` string - `DateTimeOriginal` string - `CreateDate` string - `ShutterSpeedValue` number - `ApertureValue` number - `ExposureCompensation` number - `MeteringMode` integer - `Flash` integer - `BrightnessValue` number - `MaxApertureValue` number - `LightSource` integer - `FocalLength` number - `UserComment` string - `SensingMethod` integer - `SceneType` string - `FocalLengthIn35mmFormat` integer - `LensModel` string - `SubSecTime` string - `FlashpixVersion` string - `ColorSpace` integer - `ExifImageWidth` integer - `ExifImageHeight` integer - `InteropOffset` integer - `FocalPlaneXResolution` number - `FocalPlaneYResolution` number - `FocalPlaneResolutionUnit` integer - `CustomRendered` integer - `ExposureMode` integer - `WhiteBalance` integer - `SceneCaptureType` integer - `gps` Gps — Object containing GPS information. - `GPSVersionID` integer[] - `GPSLatitudeRef` string - `GPSLatitude` number[] - `GPSLongitudeRef` string - `GPSLongitude` number[] - `GPSAltitudeRef` integer - `GPSAltitude` number - `GPSTimeStamp` number[] - `GPSImgDirectionRef` string - `GPSImgDirection` number - `GPSDateStamp` string - `interoperability` Interoperability — JSON object. - `InteropIndex` string - `InteropVersion` string - `makernote` object - `embeddedMetadata` EmbeddedMetadata — Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data. - `description` string — Optional text to describe the contents of the file. Can be set by the user or the ai-auto-description extension. ## Other responses - `202` — File accepted for upload. Pre transformation for video is being processed. - `400` — Bad request. - `401` — Unauthorized request. - `403` — Forbidden. ## Changes - **2026-05-28** `66c74def8906` — 5 breaking, 21 info - the `metadata/exif/exif/FocalLength` response's property type/format changed from `integer`/`` to `number`/`` for status `200` - the `metadata/exif/image/XResolution` response's property type/format changed from `integer`/`` to `number`/`` for status `200` - the `metadata/exif/image/YResolution` response's property type/format changed from `integer`/`` to `number`/`` for status `200` - the `metadata/exif/thumbnail/XResolution` response's property type/format changed from `integer`/`` to `number`/`` for status `200` - …22 more [Change history](https://skmtc.dev/imagekit-developer/apis/imagekit-api/changes/api/v1/files/upload/post.md) --- [API](https://skmtc.dev/imagekit-developer/apis/imagekit-api.md) · [All operations](https://skmtc.dev/imagekit-developer/apis/imagekit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/imagekit-developer/imagekit-api/revisions/bb3e9ff84b3e/schema)