FileUploadV1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/imagekit/main/json-schema/imagekit-fileuploadv1.json",
  "title": "FileUploadV1",
  "description": "ImageKit FileUploadV1 schema",
  "type": "object",
  "required": [
    "file",
    "fileName"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "contentEncoding": "binary",
      "description": "The API accepts any of the following:\n\n- **Binary data** \u2013 send the raw bytes as `multipart/form-data`.\n- **HTTP / HTTPS URL** \u2013 a publicly reachable URL that ImageKit\u2019s servers can fetch.\n- **Base64 string** \u2013 the file encoded as a Base64 data URI or plain Base64.\n\nWhen supplying a URL, the server must receive the response headers within 8 seconds; otherwise the request fails with 400 Bad Request.\n",
      "example": "https://www.example.com/path/to-image.jpg"
    },
    "fileName": {
      "type": "string",
      "description": "The name with which the file has to be uploaded.\nThe file name can contain:\n\n  - Alphanumeric Characters: `a-z`, `A-Z`, `0-9`.\n  - Special Characters: `.`, `-`\n\nAny other character including space will be replaced by `_`\n"
    },
    "publicKey": {
      "type": "string",
      "description": "Your ImageKit.io public key. This field is only required for authentication when uploading a file from the client side.\n"
    },
    "signature": {
      "type": "string",
      "description": "HMAC-SHA1 digest of the token+expire using your ImageKit.io private API key as a key. Learn how to create a signature on the page below. This should be in lowercase.\n\nSignature must be calculated on the server-side. This field is only required for authentication when uploading a file from the client side.\n"
    },
    "expire": {
      "type": "integer",
      "description": "The time until your signature is valid. It must be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in less than 1 hour into the future. It should be in seconds. This field is only required for authentication when uploading a file from the client side.\n"
    },
    "token": {
      "type": "string",
      "description": "A unique value that the ImageKit.io server will use to recognize and prevent subsequent retries for the same request. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. This field is only required for authentication when uploading a file from the client side.\n\n**Note**: Sending a value that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new value for this field.\n"
    },
    "useUniqueFileName": {
      "type": "boolean",
      "default": true,
      "description": "Whether to use a unique filename for this file or not.\n\nIf `true`, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename.\n\nIf `false`, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced.\n"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Set the tags while uploading the file.\nProvide an array of tag strings (e.g. `[\"tag1\", \"tag2\", \"tag3\"]`). The combined length of all tag characters must not exceed 500, and the `%` character is not allowed.\nIf this field is not specified and the file is overwritten, the existing tags will be removed.\n",
      "example": [
        "t-shirt",
        "round-neck",
        "men"
      ]
    },
    "folder": {
      "type": "string",
      "description": "The folder path in which the image has to be uploaded. If the folder(s) didn't exist before, a new folder(s) is created.\n\nThe folder name can contain:\n\n  - Alphanumeric Characters: `a-z` , `A-Z` , `0-9`\n  - Special Characters: `/` , `_` , `-`\n\nUsing multiple `/` creates a nested folder.\n",
      "default": "/"
    },
    "isPrivateFile": {
      "type": "boolean",
      "default": false,
      "description": "Whether to mark the file as private or not.\n\nIf `true`, the file is marked as private and is accessible only using named transformation or signed URL.\n"
    },
    "isPublished": {
      "type": "boolean",
      "default": true,
      "description": "Whether to upload file as published or not.\n\nIf `false`, the file is marked as unpublished, which restricts access to the file only via the media library. Files in draft or unpublished state can only be publicly accessed after being published.\n\nThe option to upload in draft state is only available in custom enterprise pricing plans.\n"
    },
    "customCoordinates": {
      "type": "string",
      "description": "Define an important area in the image. This is only relevant for image type files.\n\n  - To be passed as a string with the x and y coordinates of the top-left corner, and width and height of the area of interest in the format `x,y,width,height`. For example - `10,10,100,100`\n  - Can be used with fo-customtransformation.\n  - If this field is not specified and the file is overwritten, then customCoordinates will be removed.\n"
    },
    "responseFields": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tags",
          "customCoordinates",
          "isPrivateFile",
          "embeddedMetadata",
          "isPublished",
          "customMetadata",
          "metadata",
          "selectedFieldsSchema"
        ]
      },
      "description": "Array of response field keys to include in the API response body.\n",
      "example": [
        "tags",
        "customCoordinates",
        "isPrivateFile"
      ]
    },
    "extensions": {
      "$ref": "#/components/schemas/Extensions"
    },
    "webhookUrl": {
      "type": "string",
      "format": "uri",
      "description": "The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure) about the webhook payload structure.\n"
    },
    "overwriteFile": {
      "type": "boolean",
      "default": true,
      "description": "If `false` and `useUniqueFileName` is also `false`, and a file already exists at the exact location, upload API will return an error immediately.\n"
    },
    "overwriteAITags": {
      "type": "boolean",
      "default": true,
      "description": "If set to `true` and a file already exists at the exact location, its AITags will be removed. Set `overwriteAITags` to `false` to preserve AITags.\n"
    },
    "overwriteTags": {
      "type": "boolean",
      "default": true,
      "description": "If the request does not have `tags`, and a file already exists at the exact location, existing tags will be removed.\n"
    },
    "overwriteCustomMetadata": {
      "type": "boolean",
      "default": true,
      "description": "If the request does not have `customMetadata`, and a file already exists at the exact location, existing customMetadata will be removed.\n"
    },
    "customMetadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "JSON key-value pairs to associate with the asset. Create the custom metadata fields before setting these values.\n",
      "example": {
        "brand": "Nike",
        "color": "red"
      }
    },
    "transformation": {
      "type": "object",
      "$ref": "#/components/schemas/TransformationObject"
    },
    "checks": {
      "type": "string",
      "description": "Server-side checks to run on the asset.\nRead more about [Upload API checks](/docs/api-reference/upload-file/upload-file#upload-api-checks).\n",
      "example": "\"request.folder\" : \"marketing/\"\n"
    },
    "description": {
      "type": "string",
      "description": "Optional text to describe the contents of the file.\n",
      "example": "Running shoes"
    }
  }
}