openapi.city
Sign in

Upload API Reference

File handling and image processing API

uploadcare.com/docs/api_reference ↗
Version
2024-02-12
OpenAPI
3.0.0
Endpoints
9
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

GET POST PUT PATCH DELETE

Groups 2 endpoints

POST /group

Create a file group from a set of already uploaded files.

The most common use case for creating a file group is when a user uploads
multiple files at once and then wants to display them together.

Note: A group itself and files within it MUST belong to the same project.

Note: Groups are immutable and the only way to add/remove a file to a group
is to create a new one.

operationId: Groups_createFileGroup

Request Body

multipart/form-data
schema GroupsCreateFileGroupRequest
Property Type Required
expire number optional
files[] array required
pub_key string required
signature string optional

Responses

200

The group was created successfully.
400

Request failed input parameters validation.
403

Request was not allowed.
POST /group
GET /group/info

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 7 endpoints

PUT /<presigned-url-x>

The second phase is about uploading the file parts to the presigned upload URLs returned from the
/multipart/start/ endpoint.

Each uploaded part should be at least 5 MiB (5242880 bytes) in size except for the last one, which can be smaller.
You can upload the file parts in parallel provided that the byte order stays unchanged.

Note: You MUST define Content-Type header for your data.

operationId: Upload_individualFilePartsPut

Request Body

application/octet-stream
schema UploadIndividualFilePartsPutRequest

Responses

2XX

A file part has been uploaded successfully
PUT /<presigned-url-x>
POST /base

Direct file uploads comply with the RFC 7578 standard.
In other words, you can perform a direct upload by making an HTTP POST request with the Content-Type
header set to multipart/form-data.

Note: Direct file uploads support files smaller than 100 megabytes only.
If you would like to upload larger files, please use Multipart Uploads instead.

File upload example with curl:

curl -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" -F "my_file.jpg=@my_file.jpg" "https://upload.uploadcare.com/base/"
operationId: Upload_directUpload

Request Body

multipart/form-data
schema UploadDirectUploadRequest
Property Type Required
expire number optional
signature string optional
{filename} array required
metadata[{key}] string optional
UPLOADCARE_STORE string optional
UPLOADCARE_PUB_KEY string required

Responses

200

The file was uploaded successfully.
400

Request failed input parameters validation.
403

Request was not allowed.
413

The size of the request is too large.
429

Request was throttled.
POST /base
POST /from_url

Uploadcare can fetch a file from a publicly available URL and then automatically upload the
fetched file to your project.

Upload tokens

Requests to the endpoint return a JSON dictionary with a token that can be further used
to check the status of the upload
request.

Note: The token is not a file ID and can’t be used to address the file directly.
The actual file ID should be retrieved by calling the /from_url/status/ endpoint.

Duplicates prevention

By default, every call to the /from_url/ endpoint with the same source_url results in
a new upload leading to file duplication.

If you would like Uploadcare to keep track of the requested URLs and avoid the duplicate
uploads, pass the save_URL_duplicates and check_URL_duplicates parameters described below.

operationId: Upload_fromUrlFiles

Request Body

multipart/form-data
schema UploadFromUrlFilesRequest
Property Type Required
store string optional
expire number optional
pub_key string required
filename string optional
signature string optional
source_url string required
metadata[{key}] string optional
save_URL_duplicates string optional
check_URL_duplicates string optional

Responses

200

Status Token or File Info of an already downloaded file.
400

Request failed input parameters validation.
403

Request was not allowed.
429

Request was throttled.
POST /from_url
GET /from_url/status

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

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
POST /multipart/complete

Once all the file parts have been uploaded successfully, complete the
upload session to assemble all the file parts into a single resulting file.

operationId: Upload_completeMultipartUpload

Request Body

multipart/form-data
schema UploadCompleteMultipartUploadRequest
Property Type Required
uuid string required
UPLOADCARE_PUB_KEY string required

Responses

200

The file was uploaded successfully.
400

Request failed input parameters validation.
403

Request was not allowed.
404

File with specified UUID was not found.
POST /multipart/complete
POST /multipart/start

Multipart uploads should be used if you need to upload files larger than 100 megabytes or if you want to
explicitly trigger AWS S3 Transfer Acceleration.
When you use Multipart Uploads your files go straight to AWS S3 bypassing our upload instances.

To upload large files, 3 requests are sent in sequence:

  1. /multipart/start/
  2. <presigned-url-x>
  3. /multipart/complete/.

Note: Multipart uploads support files larger than 10 megabytes only.

operationId: Upload_startMultipart

Request Body

multipart/form-data
schema UploadStartMultipartRequest
Property Type Required
size integer required
expire number optional
filename string required
part_size integer optional
signature string optional
content_type string required
metadata[{key}] string optional
UPLOADCARE_STORE string optional
UPLOADCARE_PUB_KEY string required

Responses

200

Multipart upload started successfully.
400

Request failed input parameters validation.
403

Request was not allowed.
429

Request was throttled.
POST /multipart/start

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