# Create Upload

Start an upload to AWS S3, Azure Blob, SharePoint or Google Drive and get the upload URL to send the file to.

> Kind: REST endpoint · Updated: Sep 25, 2026 · POST /v1/uploads

Starts an upload and returns the uploadUrl to send the file to. For the whole flow, see Upload a File.

### Header parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string | required | Bearer API_Key. See Authentication. |
| Content-Type | string | required | application/json |

### Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| library | string | required | s3, azure, sharepoint or google, connected to your account. |
| name | string | required | The file name with its extension, up to 255 characters. |
| size | integer | required | The file's exact size in bytes, up to 21,474,836,480 (20 GB). |
| chunkSize | integer | optional | Piece 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 storage | SharePoint: 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 | optional | The folder to upload into, as the library's own folder id. Left out, the root of the library or drive. |
| folderPath | string | optional | Folders under folderId to put the file in, for example Contracts/2026. Missing ones are created. Not on Google Drive. |
| conflictBehavior | string | optional | When 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 | optional | Upload a new version of this file. It keeps the file's name and folder; name needs the same extension. |
| mimeType | string | optional | The content type, used only when name has no extension CloudFiles recognises. |

Any other field is refused with 400 COMMON/VALIDATION_FAILED.

## Example request

**cURL**
```bash
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.

```json
{
  "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

| Status | errorCode | What it means |
|---|---|---|
| 400 | COMMON/VALIDATION_FAILED | A field is missing, mistyped or unknown, or the library is not connected. |
| 403 | COMMON/FORBIDDEN | The API key is missing or unknown. |
| 404 | COMMON/NOT_FOUND | folderId does not exist. |
| 409 | UPLOAD/NAME_CONFLICT | A file of this name exists and conflictBehavior is fail. |
| 409 | UPLOAD/NAME_RESERVED | Another open upload is writing this file; details.uploadId names it. |
| 413 | UPLOAD/TOO_LARGE | The file is over 20 GB. |
| 429 | UPLOAD/TOO_MANY_OPEN_SESSIONS | Your account has 50 open uploads. |

Upload Errors lists every code and what to do.