# Creates a multipart external upload

`POST /uploads/create-multipart.json`

Creates a multipart upload in the external storage provider, storing
a temporary reference to the external upload similar to /get-presigned-put.

You must have the correct permissions and CORS settings configured in your
external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and `enable_direct_s3_uploads` must
be set to true for this endpoint to function.



Authentication: no security requirement declared for this operation.

Request body: application/json

Type: any

- `upload_type` (required)
  Type: string
  
  enum: ["avatar","profile_background","card_background","custom_emoji","composer"]

- `file_name` (required)
  Type: string
  
  Example:
  
  ```json
  "IMG_2021.jpeg"
  ```

- `file_size` (required)
  Type: integer
  
  File size should be represented in bytes.
  
  Example:
  
  ```json
  4096
  ```

- `metadata` (optional)
  Type: object
  
  - `sha1-checksum` (optional)
    Type: string
    
    The SHA1 checksum of the upload binary blob. Optionally
    be provided and serves as an additional security check when
    later processing the file in complete-external-upload endpoint.
  
  Additional properties: false

Additional properties: false

Responses:

- 200: external upload initialized

Content type: application/json

Type: any

- `key` (required)
  Type: string
  
  The path of the temporary file on the external storage
  service.
  
  Example:
  
  ```json
  "temp/site/uploads/default/12345/67890.jpg"
  ```

- `external_upload_identifier` (required)
  Type: string
  
  The identifier of the multipart upload in the external
  storage provider. This is the multipart upload_id in AWS S3.
  
  Example:
  
  ```json
  "84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ"
  ```

- `unique_identifier` (required)
  Type: string
  
  A unique string that identifies the external upload.
  This must be stored and then sent in the /complete-multipart
  and /batch-presign-multipart-parts endpoints.
  
  Example:
  
  ```json
  "66e86218-80d9-4bda-b4d5-2b6def968705"
  ```

Additional properties: false

## Examples

### cURL

```bash
curl -X POST 'https://discourse.example.com/uploads/create-multipart.json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "upload_type": "avatar",
  "file_name": "IMG_2021.jpeg",
  "file_size": 4096,
  "metadata": {
    "sha1-checksum": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "upload_type": "avatar",
  "file_name": "IMG_2021.jpeg",
  "file_size": 4096,
  "metadata": {
    "sha1-checksum": "string"
  }
}`;

const response = await fetch('https://discourse.example.com/uploads/create-multipart.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "upload_type": "avatar",
  "file_name": "IMG_2021.jpeg",
  "file_size": 4096,
  "metadata": {
    "sha1-checksum": "string"
  }
}'''

response = requests.post(
    'https://discourse.example.com/uploads/create-multipart.json',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```