# Assets

## Download

**post** `/v1/assets/download`

Download a Matrix asset using its mxc:// or localmxc:// URL to the device running Beeper Desktop and return the local file URL.

### Body Parameters

- `url: string`

  Matrix content URL (mxc:// or localmxc://) for the asset to download.

### Returns

- `error: optional string`

  Error message if the download failed.

- `srcURL: optional string`

  Local file URL to the downloaded asset.

### Example

```http
curl http://localhost:23373/v1/assets/download \
    -H 'Content-Type: application/json' \
    -d '{
          "url": "mxc://example.org/Q4x9CqGz1pB3Oa6XgJ"
        }'
```

## Upload

**post** `/v1/assets/upload`

Upload a file to a temporary location using multipart/form-data. Returns an uploadID that can be referenced when sending messages with attachments.

### Returns

- `duration: optional number`

  Duration in seconds (audio/videos)

- `error: optional string`

  Error message if upload failed

- `fileName: optional string`

  Resolved filename

- `fileSize: optional number`

  File size in bytes

- `height: optional number`

  Height in pixels (images/videos)

- `mimeType: optional string`

  Detected or provided MIME type

- `srcURL: optional string`

  Local file URL (file://) for the uploaded asset

- `uploadID: optional string`

  Unique upload ID for this asset

- `width: optional number`

  Width in pixels (images/videos)

### Example

```http
curl http://localhost:23373/v1/assets/upload \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@/path/to/file'
```

## Upload Base64

**post** `/v1/assets/upload/base64`

Upload a file using a JSON body with base64-encoded content. Returns an uploadID that can be referenced when sending messages with attachments. Alternative to the multipart upload endpoint.

### Body Parameters

- `content: string`

  Base64-encoded file content (max ~500MB decoded)

- `fileName: optional string`

  Original filename. Generated if omitted

- `mimeType: optional string`

  MIME type. Auto-detected from magic bytes if omitted

### Returns

- `duration: optional number`

  Duration in seconds (audio/videos)

- `error: optional string`

  Error message if upload failed

- `fileName: optional string`

  Resolved filename

- `fileSize: optional number`

  File size in bytes

- `height: optional number`

  Height in pixels (images/videos)

- `mimeType: optional string`

  Detected or provided MIME type

- `srcURL: optional string`

  Local file URL (file://) for the uploaded asset

- `uploadID: optional string`

  Unique upload ID for this asset

- `width: optional number`

  Width in pixels (images/videos)

### Example

```http
curl http://localhost:23373/v1/assets/upload/base64 \
    -H 'Content-Type: application/json' \
    -d '{
          "content": "x"
        }'
```

## Serve

**get** `/v1/assets/serve`

Stream a file given an mxc://, localmxc://, or file:// URL. Downloads first if not cached. Supports Range requests for seeking in large files.

### Query Parameters

- `url: string`

  Asset URL to serve. Accepts mxc://, localmxc://, or file:// URLs.

### Example

```http
curl http://localhost:23373/v1/assets/serve
```