# Upload an item

`POST /item.upload`

## Description

Upload a file so that it can be sent as a chat message attachment.
The returned object contains an item ID which can be used with [chat.post](/docs/chat-api/chat-post).

Unlike other endpoints, this uses raw binary upload with metadata in HTTP headers
rather than JSON. This is more efficient for file transfers.

**Limits:**
- Maximum file size: 10 MB

**Supported Content Types:**

| Content-Type | In-Product Behavior |
|--------------|---------------------|
| `image/png`, `image/jpeg`, `image/gif`, `image/webp` | Displayed inline with preview thumbnail |
| `application/octet-stream` | Download link only (no preview) |

**Important:** Use `application/octet-stream` for **any file type not listed above** (e.g., `.txt`, `.docx`, `.xlsx`, `.zip`, `.pdf`, etc.).
These files will be stored and downloadable, but won't have in-product preview functionality.

**Validation:**
- The `Content-Type` header must match the actual file content (server validates this for images)
- For images, if the filename lacks the correct extension, it will be appended automatically

**Access:** Organization only.

**Required scope:** `item:write`

---

**OpenAPI Spec:** [chat.json](https://developer.ro.am/chat.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `Content-Type` | header | "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "application/octet-stream" | Yes | The MIME type of the file being uploaded.  Use `application/octet-stream` for any file type not specifically listed (txt, docx, xlsx, zip, etc.).  |
| `Content-Disposition` | header | string | Yes | Must be in the format: `attachment; filename="yourfile.png"`  The filename is required and will be used as the item name.  |

## Request Body

## Responses

### 200 - Item uploaded successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | UUID identifying this item |
| `type` | "photo" | "blob" | Yes | Type of item:  - **photo**: Images with inline preview and thumbnail   - image/jpeg, image/png, image/gif, image/webp  - **blob**: Any other file type (download only, no preview)   - application/octet |
| `mime` | string | No | MIME type of the file (e.g., "application/octet-stream"). May be omitted for photo items where the type is inferred from the image format.  |
| `created` | string | Yes | Timestamp when the item was created |
| `name` | string | Yes | Name of the item (typically the filename). |
| `url` | string | Yes | URL for the uploaded item. |
| `thumbnail` | string | No | URL for a thumbnail of the uploaded item (photo type only). This may be equal to the item's main URL if it is suitable to use as a thumbnail.  |
| `size` | integer | No | Size of the item in bytes |
| `width` | integer | No | Width in pixels (images only) |
| `height` | integer | No | Height in pixels (images only) |


#### Example Response

```json
{
  "id": "019be84b-0fa8-788f-8850-96de4cc39130",
  "type": "photo",
  "created": "2026-01-21T10:30:00Z",
  "name": "screenshot.png",
  "url": "https://ro.am/card-images/019be84b-0fa8-7897-9b52-b064ddb3d185",
  "thumbnail": "https://ro.am/card-images/019be84b-0fa8-7897-9b52-b064ddb3d185",
  "size": 245678,
  "width": 1920,
  "height": 1080
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 415 - An unsupported media type was provided.

### 500 - An internal error occured.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/chat-api/item-upload*