Upload API Reference

File handling and image processing API

uploadcare.com/docs/api_reference ↗

Version

2024-02-12

OpenAPI

3.0.0

Endpoints

Schemas

106

74

Quality

Updated

3 days ago

Storage storage files image-processing

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://upload.uploadcare.com

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Groups 1 endpoints

GET /group/info Get information about a file group

Returns a JSON object with information about a file group (when the group was created,
number of the files in the group, etc).

operationId: Groups_getInfo

Parameters

Name	In	Required	Type	Description
pub_key	query	required		—
group_id	query	required	string	Group’s unique ID. Group IDs look like `UUID~N`, where the `~N` part reflects the number of the files in the group.

Responses

200

File group information was retrieved successfully.

400

Request failed input parameters validation.

403

Request was not allowed.

404

Group with specified UUID was not found.

GET /group/info

Upload 2 endpoints

GET /from_url/status Check the status of a task to fetch/upload a file from a URL

The endpoint notifies about the progress of the task by changing the value of the status field:

the field is set to waiting initially
once the system starts processing the request, the field is set to progress
if the file is fetched and uploaded successfully, the status field is set to success
and the endpoint returns a JSON object holding information about the uploaded file
if the system fails to fetch/upload the file, the status field is set to error and
the error field is set to the cause of the error.

operationId: Upload_urlStatusGet

Parameters

Name	In	Required	Type	Description
token	query	required	string	Token returned by the `/from_url/` endpoint that identifies a request to fetch/upload a file from a URL.

Responses

200

Request was processed successfully.

400

Request failed input parameters validation.

GET /from_url/status

GET /info Get information about an uploaded file

Returns a JSON object with information about an uploaded file (file size, MIME type, metadata, etc).

operationId: Upload_fileInfo

Parameters

Name	In	Required	Type	Description
pub_key	query	required		—
file_id	query	required	string	File’s unique ID.

Responses

200

File information was retrieved successfully.

400

Request failed input parameters validation.

403

Request was not allowed.

404

File with specified UUID was not found.

GET /info

Load more endpoints

Schemas

object GroupsCreateFileGroup403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/publicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/publicKeyInvalidError"
    },
    {
      "$ref": "#/components/schemas/projectPublicKeyRemovedError"
    },
    {
      "$ref": "#/components/schemas/accountBlockedError"
    },
    {
      "$ref": "#/components/schemas/accountUnpaidError"
    },
    {
      "$ref": "#/components/schemas/uploadFailedError"
    },
    {
      "$ref": "#/components/schemas/accountLimitsExceededError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationError"
    },
    {
      "$ref": "#/components/schemas/signatureInvalidError"
    }
  ]
}

object GroupsCreateFileGroupRequest

{
  "type": "object",
  "required": [
    "files[]",
    "pub_key"
  ],
  "properties": {
    "expire": {
      "$ref": "#/components/schemas/expireType"
    },
    "files[]": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Set of files you want to add to the group.\nEach element can be a file UUID with or without the applied image\nprocessing operations.\n"
    },
    "pub_key": {
      "$ref": "#/components/schemas/projectPublicKeyType"
    },
    "signature": {
      "$ref": "#/components/schemas/signatureType"
    }
  }
}

object GroupsCreateFileGroupResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/requestFiledsNumberLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/postRequestParserFailedError"
    },
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/signatureRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationInvalidError"
    },
    {
      "$ref": "#/components/schemas/groupFilesInvalidError"
    },
    {
      "$ref": "#/components/schemas/groupFileURLParsingFailedError"
    },
    {
      "$ref": "#/components/schemas/groupFilesNotFoundError"
    }
  ]
}

object GroupsGetInfo403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/publicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/publicKeyInvalidError"
    }
  ]
}

object GroupsGetInfoResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/groupIdRequiredError"
    }
  ]
}

object UploadCompleteMultipartUpload403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/uploadcarePublicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/uploadcarePublicKeyInvalidError"
    }
  ]
}

object UploadCompleteMultipartUploadRequest

{
  "type": "object",
  "required": [
    "UPLOADCARE_PUB_KEY",
    "uuid"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "format": "uuid",
      "example": "67947755-1584-4e3f-902b-d4e2bf76a841",
      "description": "File's UUID from the `/multipart/start/` endpoint."
    },
    "UPLOADCARE_PUB_KEY": {
      "$ref": "#/components/schemas/projectPublicKeyType"
    }
  }
}

object UploadCompleteMultipartUploadResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/requestFiledsNumberLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/postRequestParserFailedError"
    },
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/multipartFileIdRequiredError"
    },
    {
      "$ref": "#/components/schemas/uuidInvalidError"
    },
    {
      "$ref": "#/components/schemas/multipartFileAlreadyUploadedError"
    },
    {
      "$ref": "#/components/schemas/multipartUploadSizeTooLargeError"
    },
    {
      "$ref": "#/components/schemas/multipartUploadSizeTooSmallError"
    },
    {
      "$ref": "#/components/schemas/multipartFileCompletionFailedError"
    },
    {
      "$ref": "#/components/schemas/fileTypeForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileInfectedError"
    }
  ]
}

object UploadDirectUpload400Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/requestFiledsNumberLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/postRequestParserFailedError"
    },
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyDuplicatedError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeysNumberTooBigError"
    },
    {
      "$ref": "#/components/schemas/signatureRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationInvalidError"
    },
    {
      "$ref": "#/components/schemas/filesRequiredError"
    },
    {
      "$ref": "#/components/schemas/fileSizeLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/fileTypeForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileInfectedError"
    }
  ]
}

object UploadDirectUpload403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/uploadcarePublicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/uploadcarePublicKeyInvalidError"
    },
    {
      "$ref": "#/components/schemas/autoStoreDisabledError"
    },
    {
      "$ref": "#/components/schemas/projectPublicKeyRemovedError"
    },
    {
      "$ref": "#/components/schemas/accountBlockedError"
    },
    {
      "$ref": "#/components/schemas/accountUnpaidError"
    },
    {
      "$ref": "#/components/schemas/uploadFailedError"
    },
    {
      "$ref": "#/components/schemas/accountLimitsExceededError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationError"
    },
    {
      "$ref": "#/components/schemas/signatureInvalidError"
    }
  ]
}

string UploadDirectUpload413Response

{
  "type": "string",
  "default": "The size of the request is too large."
}

string UploadDirectUpload429Response

{
  "type": "string",
  "default": "Request was throttled."
}

object UploadDirectUploadRequest

{
  "type": "object",
  "required": [
    "{filename}",
    "UPLOADCARE_PUB_KEY"
  ],
  "properties": {
    "expire": {
      "$ref": "#/components/schemas/expireType"
    },
    "signature": {
      "$ref": "#/components/schemas/signatureType"
    },
    "{filename}": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "binary"
      },
      "description": "File's content"
    },
    "metadata[{key}]": {
      "$ref": "#/components/schemas/metadataValue"
    },
    "UPLOADCARE_STORE": {
      "$ref": "#/components/schemas/storeType"
    },
    "UPLOADCARE_PUB_KEY": {
      "$ref": "#/components/schemas/projectPublicKeyType"
    }
  }
}

object UploadDirectUploadResponse

{
  "type": "object",
  "example": {
    "my_file.jpg": "17be4678-dab7-4bc7-8753-28914a22960a"
  },
  "properties": {
    "filename": {
      "type": "string",
      "format": "uuid"
    }
  },
  "description": "JSON object where the key is the file name of the uploaded file and\nthe value is the unique ID of the file on our systems.\n"
}

object UploadFileInfo403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/publicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/publicKeyInvalidError"
    }
  ]
}

object UploadFileInfoResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileIdRequiredError"
    },
    {
      "$ref": "#/components/schemas/fileIdInvalidError"
    }
  ]
}

object UploadFromUrlFiles400Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/requestFiledsNumberLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/postRequestParserFailedError"
    },
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyDuplicatedError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeysNumberTooBigError"
    },
    {
      "$ref": "#/components/schemas/signatureRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationInvalidError"
    },
    {
      "$ref": "#/components/schemas/sourceURLRequiredError"
    },
    {
      "$ref": "#/components/schemas/urlParsingFailedError"
    },
    {
      "$ref": "#/components/schemas/urlSchemeRequiredError"
    },
    {
      "$ref": "#/components/schemas/urlSchemeInvalidError"
    },
    {
      "$ref": "#/components/schemas/urlHostRequiredError"
    },
    {
      "$ref": "#/components/schemas/urlBlacklistedError"
    },
    {
      "$ref": "#/components/schemas/hostnameNotFoundError"
    },
    {
      "$ref": "#/components/schemas/urlHostMalformedError"
    },
    {
      "$ref": "#/components/schemas/urlHostPrivateIPForbiddenError"
    }
  ]
}

object UploadFromUrlFiles403Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/publicKeyRequiredError"
    },
    {
      "$ref": "#/components/schemas/publicKeyInvalidError"
    },
    {
      "$ref": "#/components/schemas/autoStoreDisabledError"
    },
    {
      "$ref": "#/components/schemas/projectPublicKeyRemovedError"
    },
    {
      "$ref": "#/components/schemas/accountBlockedError"
    },
    {
      "$ref": "#/components/schemas/accountUnpaidError"
    },
    {
      "$ref": "#/components/schemas/uploadFailedError"
    },
    {
      "$ref": "#/components/schemas/accountLimitsExceededError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationError"
    },
    {
      "$ref": "#/components/schemas/signatureInvalidError"
    }
  ]
}

object UploadFromUrlFilesRequest

{
  "type": "object",
  "required": [
    "pub_key",
    "source_url"
  ],
  "properties": {
    "store": {
      "$ref": "#/components/schemas/storeType"
    },
    "expire": {
      "$ref": "#/components/schemas/expireType"
    },
    "pub_key": {
      "$ref": "#/components/schemas/projectPublicKeyType"
    },
    "filename": {
      "type": "string",
      "example": "googlelogo_color_272x92dp.png",
      "description": "Sets the file name of the resource fetched from the source URL.\nIf not defined, the file name is obtained from either HTTP\nresponse headers or the `source_url`'s path.\n\n**Note:** The filename will be sanitized to only contain the following symbols:\n`abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._`.\n"
    },
    "signature": {
      "$ref": "#/components/schemas/signatureType"
    },
    "source_url": {
      "type": "string",
      "format": "uri",
      "example": "https://source.unsplash.com/featured",
      "description": "Source URL of the file to fetch and upload.\n\n**Note**: The URL should point to a resource publicly available via HTTP/HTTPS.\n"
    },
    "metadata[{key}]": {
      "$ref": "#/components/schemas/metadataValue"
    },
    "save_URL_duplicates": {
      "enum": [
        "0",
        "1"
      ],
      "type": "string",
      "example": "1",
      "description": "Determines if the requested `source_url` should be kept in the history of\nfetched/uploaded URLs. If the value is not defined explicitly, it is set\nto the value of the `check_URL_duplicates` parameter.\n"
    },
    "check_URL_duplicates": {
      "enum": [
        "0",
        "1"
      ],
      "type": "string",
      "default": "0",
      "example": "1",
      "description": "If set to \"1\", enables the `source_url` duplicates prevention.\nSpecifically, if the `source_url` had already been fetched and uploaded previously,\nthis request will return information about the already uploaded file.\n"
    }
  }
}

object UploadFromUrlFilesResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/fromURLUploadResponseSchema"
    },
    {
      "$ref": "#/components/schemas/fileUploadInfoFromURL"
    }
  ]
}

object UploadIndividualFilePartsPutRequest

{
  "type": "object",
  "description": "Part of the uploaded file.\n\nDon't include `https://upload.uploadcare.com/` in this request:\n\n```\ncurl -X PUT \"<presigned-url-x>\" -H \"Content-Type: application/octet-stream\" --data <data-part>\n```\n"
}

object UploadStartMultipart400Response

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/requestFiledsNumberLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/postRequestParserFailedError"
    },
    {
      "$ref": "#/components/schemas/nullCharactersForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyDuplicatedError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeyLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueEmptyError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueForbiddenError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataValueLengthTooBigError"
    },
    {
      "$ref": "#/components/schemas/fileMetadataKeysNumberTooBigError"
    },
    {
      "$ref": "#/components/schemas/signatureRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationRequiredError"
    },
    {
      "$ref": "#/components/schemas/signatureExpirationInvalidError"
    },
    {
      "$ref": "#/components/schemas/requestParamRequiredError"
    },
    {
      "$ref": "#/components/schemas/multipartSizeInvalidError"
    },
    {
      "$ref": "#/components/schemas/multipartFileSizeLimitExceededError"
    },
    {
      "$ref": "#/components/schemas/multipartFileSizeTooSmallError"
    },
    {
      "$ref": "#/components/schemas/multipartPartSizeInvalidError"
    },
    {
      "$ref": "#/components/schemas/multipartPartSizeTooSmallError"
    },
    {
      "$ref": "#/components/schemas/multipartPartSizeTooBigError"
    }
  ]
}

object UploadStartMultipartRequest

{
  "type": "object",
  "required": [
    "filename",
    "content_type",
    "size",
    "UPLOADCARE_PUB_KEY"
  ],
  "properties": {
    "size": {
      "type": "integer",
      "example": 27796904,
      "description": "Precise file size of the uploaded file (in bytes).\n**Note**: The size should not exceed max file size cap for your project.\n"
    },
    "expire": {
      "$ref": "#/components/schemas/expireType"
    },
    "filename": {
      "type": "string",
      "example": "myfile.mp4",
      "description": "Original file name of the uploaded file"
    },
    "part_size": {
      "type": "integer",
      "default": 5242880,
      "example": 10485760,
      "maximum": 5368709120,
      "minimum": 5242880,
      "description": "Multipart Uploads expect that you will split the uploaded file into equally sized\nparts (except for the last part) and then will upload them to AWS S3 (possibly in parallel).\nBy default, we assume that you will upload the files in 5 megabyte chunks,\nso we return a list of presigned AWS S3 URLs accordingly.\nIf you intend to upload large files (for example, larger than a gigabyte),\nwe recommend to bump the part size and to pass the expected chunk size\nto us as a value of the `part_size` parameter (in bytes).\n"
    },
    "signature": {
      "$ref": "#/components/schemas/signatureType"
    },
    "content_type": {
      "type": "string",
      "example": "video/mp4",
      "description": "File's MIME-type."
    },
    "metadata[{key}]": {
      "$ref": "#/components/schemas/metadataValue"
    },
    "UPLOADCARE_STORE": {
      "$ref": "#/components/schemas/storeType"
    },
    "UPLOADCARE_PUB_KEY": {
      "$ref": "#/components/schemas/projectPublicKeyType"
    }
  },
  "description": "Multipart upload parameters to start multipart uploading."
}

object UploadStartMultipartResponse

{
  "type": "object",
  "example": {
    "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841",
    "parts": [
      "<presigned-url-1>",
      "<presigned-url-2>",
      "<presigned-url-3>",
      "<presigned-url-4>",
      "<presigned-url-5>"
    ]
  },
  "required": [
    "uuid",
    "parts"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "format": "uuid",
      "description": "File's UUID."
    },
    "parts": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "Upload file parts here."
      }
    }
  }
}

object UploadUrlStatusGetResponse

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/fileUploadInfoWaitingStatus"
    },
    {
      "$ref": "#/components/schemas/fileUploadInfoProgressStatus"
    },
    {
      "$ref": "#/components/schemas/fileUploadInfoSuccessStatus"
    },
    {
      "$ref": "#/components/schemas/fileUploadInfoErrorStatus"
    },
    {
      "$ref": "#/components/schemas/fileUploadInfoUnknownStatus"
    }
  ]
}

string accountBlockedError

{
  "type": "string",
  "default": "Account has been blocked.",
  "example": "#/components/examples/accountBlockedError/value"
}

string accountLimitsExceededError

{
  "type": "string",
  "default": "Account has reached its limits.",
  "example": "#/components/examples/accountLimitsExceededError/value"
}

string accountUnpaidError

{
  "type": "string",
  "default": "Account has been blocked for non payment.",
  "example": "#/components/examples/accountUnpaidError/value"
}

string autoStoreDisabledError

{
  "type": "string",
  "default": "Autostore is disabled.",
  "example": "#/components/examples/autoStoreDisabledError/value"
}

object contentInfo

{
  "type": "object",
  "nullable": true,
  "properties": {
    "mime": {
      "type": "object",
      "required": [
        "mime",
        "type",
        "subtype"
      ],
      "properties": {
        "mime": {
          "type": "string",
          "example": "image/jpeg",
          "description": "Full MIME type."
        },
        "type": {
          "type": "string",
          "example": "image",
          "description": "Type of MIME type."
        },
        "subtype": {
          "type": "string",
          "example": "jpeg",
          "description": "Subtype of MIME type."
        }
      },
      "description": "MIME type."
    },
    "image": {
      "$ref": "#/components/schemas/schemas-imageInfo"
    },
    "video": {
      "$ref": "#/components/schemas/videoInfo"
    }
  },
  "description": "Information about file content."
}

number expireType

{
  "type": "number",
  "example": 1454902434,
  "description": "`expire` must be sent along with your upload request if you would like to use signed uploads.\nThe parameter defines the time during which your signature is valid. It's a UNIX timestamp.\nSee [signed uploads](https://uploadcare.com/docs/security/secure-uploads/) for details.\n"
}

string fileIdInvalidError

{
  "type": "string",
  "default": "file_id is invalid.",
  "example": "#/components/examples/fileIdInvalidError/value"
}

string fileIdRequiredError

{
  "type": "string",
  "default": "file_id is required.",
  "example": "#/components/examples/fileIdRequiredError/value"
}

string fileInfectedError

{
  "type": "string",
  "default": "The file is infected by <VIRUS-NAME> virus.",
  "example": "#/components/examples/fileInfectedError/value"
}

string fileMetadataKeyDuplicatedError

{
  "type": "string",
  "default": "File's metadata key `<KEY>` has a duplicate.",
  "example": "#/components/examples/fileMetadataKeyDuplicatedError/value"
}

string fileMetadataKeyEmptyError

{
  "type": "string",
  "default": "File's metadata key can not be empty.",
  "example": "#/components/examples/fileMetadataKeyEmptyError/value"
}

string fileMetadataKeyForbiddenError

{
  "type": "string",
  "default": "File's metadata key `<KEY>` contains symbols not allowed by the metadata key format.",
  "example": "#/components/examples/fileMetadataKeyForbiddenError/value"
}

string fileMetadataKeyLengthTooBigError

{
  "type": "string",
  "default": "Length of file metadata key `<KEY>` can not be more than <LENGTH> symbols.",
  "example": "#/components/examples/fileMetadataKeyLengthTooBigError/value"
}

string fileMetadataKeysNumberTooBigError

{
  "type": "string",
  "default": "A file can not have more than <NUMBER> metadata keys.",
  "example": "#/components/examples/fileMetadataKeysNumberTooBigError/value"
}

string fileMetadataValueEmptyError

{
  "type": "string",
  "default": "Value of the file metadata key `<KEY>` can not be empty.",
  "example": "#/components/examples/fileMetadataValueEmptyError/value"
}

string fileMetadataValueForbiddenError

{
  "type": "string",
  "default": "Value of file metadata key `<KEY>` contains symbols not allowed by the metadata value format.",
  "example": "#/components/examples/fileMetadataValueForbiddenError/value"
}

string fileMetadataValueLengthTooBigError

{
  "type": "string",
  "default": "Value of file metadata's key `<KEY>` can not be more than <LENGTH> symbols in length.",
  "example": "#/components/examples/fileMetadataValueLengthTooBigError/value"
}

string fileNotFoundError

{
  "type": "string",
  "default": "File is not found.",
  "example": "#/components/examples/fileNotFoundError/value"
}

string fileSizeLimitExceededError

{
  "type": "string",
  "default": "File is too large.",
  "example": "#/components/examples/fileSizeLimitExceededError/value"
}

string fileTypeForbiddenError

{
  "type": "string",
  "default": "Uploading of these file types is not allowed.",
  "example": "#/components/examples/fileTypeForbiddenError/value"
}

object fileUploadInfo

{
  "type": "object",
  "example": {
    "done": 2667636,
    "size": 2667636,
    "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
    "total": 2667636,
    "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
    "filename": "IMG0412_123.JPG",
    "is_image": true,
    "is_ready": true,
    "metadata": {
      "pet": "cat",
      "subsystem": "uploader"
    },
    "is_stored": true,
    "mime_type": "image/jpeg",
    "image_info": {
      "dpi": [
        72,
        72
      ],
      "width": 3024,
      "format": "JPEG",
      "height": 4032,
      "sequence": false,
      "color_mode": "RGB",
      "orientation": 6,
      "geo_location": {
        "latitude": 55.62013611111111,
        "longitude": 37.66299166666666
      },
      "datetime_original": "2018-08-20T08:59:50"
    },
    "video_info": null,
    "content_info": {
      "mime": {
        "mime": "image/jpeg",
        "type": "image",
        "subtype": "jpeg"
      },
      "image": {
        "dpi": [
          72,
          72
        ],
        "width": 3024,
        "format": "JPEG",
        "height": 4032,
        "sequence": false,
        "color_mode": "RGB",
        "orientation": 6,
        "geo_location": {
          "latitude": 55.62013611111111,
          "longitude": 37.66299166666666
        },
        "datetime_original": "2018-08-20T08:59:50"
      }
    },
    "original_filename": "IMG-0412_123.JPG"
  },
  "required": [
    "uuid",
    "file_id",
    "size",
    "total",
    "done",
    "original_filename",
    "filename",
    "mime_type",
    "image_info",
    "video_info",
    "content_info",
    "metadata",
    "is_image",
    "is_stored",
    "is_ready"
  ],
  "properties": {
    "done": {
      "type": "integer",
      "example": 145212,
      "description": "Same as `size`."
    },
    "size": {
      "type": "integer",
      "example": 145212,
      "description": "File's size in bytes."
    },
    "uuid": {
      "type": "string",
      "format": "uuid",
      "example": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
      "description": "File's unique ID."
    },
    "total": {
      "type": "integer",
      "example": 145212,
      "description": "Same as `size`."
    },
    "file_id": {
      "type": "string",
      "format": "uuid",
      "example": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
      "description": "Same as `uuid`"
    },
    "filename": {
      "type": "string",
      "example": "testimage_1.jpg",
      "description": "Sanitized `original_filename`."
    },
    "is_image": {
      "type": "boolean",
      "example": true,
      "description": "True if the uploaded file is an image of a supported file format."
    },
    "is_ready": {
      "type": "boolean",
      "example": true,
      "description": "True if the file is ready to be fetched from Uploadcare's CDN."
    },
    "metadata": {
      "$ref": "#/components/schemas/metadata"
    },
    "is_stored": {
      "type": "boolean",
      "example": true,
      "description": "True if the file has been marked as stored."
    },
    "mime_type": {
      "type": "string",
      "example": "image/jpeg",
      "description": "File's MIME-type."
    },
    "s3_bucket": {
      "type": "string",
      "example": "custom-s3-bucket-name",
      "nullable": true,
      "description": "Name of an AWS S3 bucket where the file is stored. Only available if you associate a Foreign Storage Bucket with your project."
    },
    "image_info": {
      "$ref": "#/components/schemas/imageInfo"
    },
    "video_info": {
      "$ref": "#/components/schemas/legacyVideoInfo"
    },
    "content_info": {
      "$ref": "#/components/schemas/contentInfo"
    },
    "original_filename": {
      "type": "string",
      "example": "test-image_1.jpg",
      "description": "Original file of the uploaded file."
    }
  },
  "description": "Information about an uploaded file."
}

object fileUploadInfoErrorStatus

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "HTTP client error: 404.",
      "description": "Human readable description of the issue with the fetch/upload task.\n"
    },
    "status": {
      "enum": [
        "error"
      ],
      "type": "string",
      "default": "error",
      "description": "The system failed to fetch and/or upload the file.\n"
    },
    "error_code": {
      "type": "string",
      "example": "DownloadFileHTTPClientError",
      "description": "Machine readable error code.\n\nNote: See the [Errors > FromURL upload errors](https://uploadcare.com/api-refs/upload-api/) section of this\npage for a full list of all possible error codes.\n"
    }
  }
}

object fileUploadInfoFromURL

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "file_info"
          ],
          "type": "string",
          "example": "file_info"
        }
      }
    },
    {
      "$ref": "#/components/schemas/fileUploadInfo"
    }
  ]
}

object fileUploadInfoProgressStatus

{
  "type": "object",
  "properties": {
    "done": {
      "type": "number",
      "example": 134427,
      "description": "How many bytes of the file have been fetched so far.\n"
    },
    "total": {
      "type": "number",
      "example": 732434,
      "nullable": true,
      "description": "The expected size of the fetched file (in bytes).\n\n**Note:** the value can be missing if the server we are fetching the file from\ndoes not provide the information or if the server is returning the file in, for\nexample, [compressed form](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding).\n"
    },
    "status": {
      "enum": [
        "progress"
      ],
      "type": "string",
      "default": "progress",
      "description": "The system is fetching/uploading the file.\n"
    }
  }
}

object fileUploadInfoSuccessStatus

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "status": {
          "enum": [
            "success"
          ],
          "type": "string",
          "default": "success",
          "description": "The file has been fetched/uploaded successfully."
        }
      }
    },
    {
      "$ref": "#/components/schemas/fileUploadInfo"
    }
  ],
  "example": {
    "done": 2667636,
    "size": 2667636,
    "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
    "total": 2667636,
    "status": "success",
    "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
    "filename": "IMG0412_123.JPG",
    "is_image": true,
    "is_ready": true,
    "metadata": {
      "pet": "cat",
      "subsystem": "uploader"
    },
    "is_stored": true,
    "mime_type": "image/jpeg",
    "image_info": {
      "dpi": [
        72,
        72
      ],
      "width": 3024,
      "format": "JPEG",
      "height": 4032,
      "sequence": false,
      "color_mode": "RGB",
      "orientation": 6,
      "geo_location": {
        "latitude": 55.62013611111111,
        "longitude": 37.66299166666666
      },
      "datetime_original": "2018-08-20T08:59:50"
    },
    "video_info": null,
    "content_info": {
      "mime": {
        "mime": "image/jpeg",
        "type": "image",
        "subtype": "jpeg"
      },
      "image": {
        "dpi": [
          72,
          72
        ],
        "width": 3024,
        "format": "JPEG",
        "height": 4032,
        "sequence": false,
        "color_mode": "RGB",
        "orientation": 6,
        "geo_location": {
          "latitude": 55.62013611111111,
          "longitude": 37.66299166666666
        },
        "datetime_original": "2018-08-20T08:59:50"
      }
    },
    "original_filename": "IMG-0412_123.JPG"
  }
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
2024-02-12	9	106	2026-05-11	current
2024-02-12	9	106	2026-04-20
2024-02-12	9	106	2026-04-16