Header parameters
ParameterDescription
Authorization
string
 requiredBearer API_Key. See Authentication.
Content-Type
string
 requiredapplication/json
Body parameters
ParameterDescription
library
string
 requireds3, azure, sharepoint or google, connected to your account.
name
string
 requiredThe file name with its extension, up to 255 characters.
size
integer
 requiredThe file's exact size in bytes, up to 21,474,836,480 (20 GB).
chunkSize
integer
 optionalPiece size in bytes, from 5,242,880 (5 MB) to 52,428,800 (50 MB). Default 20,971,520 (20 MB). Use the chunkSize in the answer, which can be lower than you asked.
driveId
string
 varies by storageSharePoint: required, the document library's drive id. Google Drive: a shared drive's id. AWS S3 and Azure Blob: one of the library's drives; the default drive when left out.
folderId
string
 optionalThe folder to upload into, as the library's own folder id. Left out, the root of the library or drive.
folderPath
string
 optionalFolders under folderId to put the file in, for example Contracts/2026. Missing ones are created. Not on Google Drive.
conflictBehavior
string
 optionalWhen a file of this name exists: fail, rename or replace. Default: your account's setting for the library (noop counts as fail), otherwise fail on AWS S3 and Azure Blob and rename on SharePoint. Not on Google Drive.
replaceFileId
string
 optionalUpload a new version of this file. It keeps the file's name and folder; name needs the same extension.
mimeType
string
 optionalThe content type, used only when name has no extension CloudFiles recognises.

Any other field is refused with 400 COMMON/VALIDATION_FAILED.

Example request

curl --request POST 'https://api.cloudfiles.io/v1/uploads' \
  --header 'Authorization: Bearer API_Key' \
  --header 'Content-Type: application/json' \
  --data '{
    "library": "s3",
    "folderPath": "Contracts/2026",
    "name": "Q3-report.pdf",
    "size": 120000000,
    "chunkSize": 52428800
  }'

Response body

201 Created. Keep uploadUrl and chunkSize. createdFolders lists the folders folderPath created.

{
  "id": "upl_66f3c1a2b4d5e6f708192a3b",
  "status": "created",
  "library": "s3",
  "driveId": "workspace",
  "name": "Q3-report.pdf",
  "size": 120000000,
  "chunkSize": 52428800,
  "chunkCount": 3,
  "maxConcurrency": 4,
  "bytesReceived": 0,
  "nextExpectedRanges": [
    "0-119999999"
  ],
  "expiresAt": "2026-09-25T11:00:00.000Z",
  "uploadUrl": "https://{upload host}/v1/uploads/Jm0Wz8cV4qRkT2yLpN6hXaB9sD1fG3jK5uE7iO0wQ_c",
  "createdFolders": [
    {
      "id": "66f3c1a2b4d5e6f708192a31",
      "name": "Contracts"
    },
    {
      "id": "66f3c1a2b4d5e6f708192a32",
      "name": "2026"
    }
  ]
}

Errors

StatuserrorCodeWhat it means
400COMMON/VALIDATION_FAILEDA field is missing, mistyped or unknown, or the library is not connected.
403COMMON/FORBIDDENThe API key is missing or unknown.
404COMMON/NOT_FOUNDfolderId does not exist.
409UPLOAD/NAME_CONFLICTA file of this name exists and conflictBehavior is fail.
409UPLOAD/NAME_RESERVEDAnother open upload is writing this file; details.uploadId names it.
413UPLOAD/TOO_LARGEThe file is over 20 GB.
429UPLOAD/TOO_MANY_OPEN_SESSIONSYour account has 50 open uploads.

Upload Errors lists every code and what to do.