# Creates an upload

`POST /uploads.json`

Authentication: no security requirement declared for this operation.

Request body: multipart/form-data

Type: any

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

- `user_id` (optional)
  Type: integer
  
  required if uploading an avatar

- `synchronous` (optional)
  Type: boolean
  
  Use this flag to return an id and url

- `file` (optional)
  Type: string, binary

Additional properties: false

Responses:

- 200: file uploaded

Content type: application/json

Type: any

- `id` (required)
  Type: integer

- `url` (required)
  Type: string

- `original_filename` (required)
  Type: string

- `filesize` (required)
  Type: integer

- `width` (required)
  Type: integer

- `height` (required)
  Type: integer

- `thumbnail_width` (required)
  Type: integer

- `thumbnail_height` (required)
  Type: integer

- `extension` (required)
  Type: string

- `short_url` (required)
  Type: string

- `short_path` (required)
  Type: string

- `retain_hours` (required)
  Type: string; nullable

- `human_filesize` (required)
  Type: string

- `dominant_color` (optional)
  Type: string; nullable

- `thumbnail` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `upload_id` (optional)
    Type: integer
  
  - `url` (optional)
    Type: string
  
  - `extension` (optional)
    Type: string
  
  - `width` (optional)
    Type: integer
  
  - `height` (optional)
    Type: integer
  
  - `filesize` (optional)
    Type: integer
  
  Additional properties: false

- `optimized_video` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `upload_id` (optional)
    Type: integer
  
  - `url` (optional)
    Type: string
  
  - `extension` (optional)
    Type: string
  
  - `filesize` (optional)
    Type: integer
  
  - `sha1` (optional)
    Type: string
  
  - `original_filename` (optional)
    Type: string
  
  Additional properties: false

Additional properties: false

## Examples

### cURL

```bash
curl -X POST 'https://discourse.example.com/uploads.json' \
  --form-string 'upload_type=avatar' \
  --form-string 'user_id=0' \
  --form-string 'synchronous=true'
```

### JavaScript

```javascript
const form = new FormData();
form.append('upload_type', 'avatar');
form.append('user_id', '0');
form.append('synchronous', 'true');
const response = await fetch('https://discourse.example.com/uploads.json', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());
```

### Python

```python
import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('upload_type', (None, 'avatar')),
        ('user_id', (None, '0')),
        ('synchronous', (None, 'true')),
    ]
    response = requests.request('POST', 'https://discourse.example.com/uploads.json', headers={}, files=files)
    print(response.text)
```