> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset uploaden

> Upload een bestand naar een chat en ontvang een permanente CDN-URL

Uploadt een bestand naar de assets van een chat en retourneert een permanente CDN-URL. Gebruik dit endpoint voor afbeeldingen, documenten, audio, video of elk ander bestand waarnaar u via een URL wilt verwijzen in uw app of workflow.

## Verzoek

```
POST /api/client-app/assets/upload
```

### Headers

| Header          | Vereist | Beschrijving          |
| --------------- | ------- | --------------------- |
| `Authorization` | Ja      | `Bearer macaly_...`   |
| `Content-Type`  | Ja      | `multipart/form-data` |

### Formulierparameters

| Veld            | Type          | Vereist | Standaard                    | Beschrijving                                                               |
| --------------- | ------------- | ------- | ---------------------------- | -------------------------------------------------------------------------- |
| `chatId`        | string        | Ja      | -                            | De chat waarnaar de asset wordt geüpload                                   |
| `file`          | file          | Ja      | -                            | Het te uploaden bestand. Maximale grootte 20 MB                            |
| `folderPath`    | string        | Nee     | -                            | Padpad gescheiden door schuine strepen, bijv. `images/products`            |
| `createFolders` | string        | Nee     | `false`                      | `"true"`, `"1"` of `"yes"` maakt ontbrekende mappen in `folderPath` aan    |
| `folderId`      | string        | Nee     | -                            | ID van een bestaande map. Stuur niet zowel `folderId` als `folderPath` mee |
| `title`         | string        | Nee     | Oorspronkelijke bestandsnaam | Weergavetitel voor de asset                                                |
| `metadata`      | string (JSON) | Nee     | -                            | JSON-object dat samen met de asset wordt opgeslagen                        |

<Note>
  Geef `folderId` of `folderPath` op, niet beide. Als u beide meestuurt, krijgt u een foutmelding 400.
</Note>

### Voorbeeldverzoek

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.macaly.com/api/client-app/assets/upload \
    -H "Authorization: Bearer macaly_abc123..." \
    -F "chatId=abc123def456" \
    -F "file=@./logo.png;type=image/png"
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append('chatId', 'abc123def456');
  form.append('file', fileBlob, 'logo.png');

  const response = await fetch('https://www.macaly.com/api/client-app/assets/upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer macaly_abc123...',
    },
    body: form,
  });

  const data = await response.json();
  console.log(data.asset.url);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://www.macaly.com/api/client-app/assets/upload',
      headers={'Authorization': 'Bearer macaly_abc123...'},
      data={'chatId': 'abc123def456'},
      files={'file': ('logo.png', open('logo.png', 'rb'), 'image/png')},
  )

  data = response.json()
  print(data['asset']['url'])
  ```
</CodeGroup>

### Uploaden naar een map

Gebruik `folderPath` voor een leesbare mapstructuur en `createFolders=true` om ontbrekende mappen op dat pad aan te maken:

```bash cURL theme={null}
curl -X POST https://www.macaly.com/api/client-app/assets/upload \
  -H "Authorization: Bearer macaly_abc123..." \
  -F "chatId=abc123def456" \
  -F "folderPath=images/products" \
  -F "createFolders=true" \
  -F "title=Product hero image" \
  -F "file=@./hero.png;type=image/png"
```

## Respons

```json theme={null}
{
  "success": true,
  "asset": {
    "assetId": "asset_123",
    "url": "https://cdn.macaly.app/user/chat/key/logo.png",
    "storageKey": "user/chat/key/logo.png",
    "contentType": "image/png",
    "fileSize": 12345,
    "type": "image",
    "folderId": "folder_123"
  }
}
```

| Veld                | Type           | Beschrijving                                            |
| ------------------- | -------------- | ------------------------------------------------------- |
| `asset.assetId`     | string         | Unieke identifier voor de asset                         |
| `asset.url`         | string         | Permanente CDN-URL voor het geüploade bestand           |
| `asset.storageKey`  | string         | Interne opslaglocatie                                   |
| `asset.contentType` | string         | MIME-type van het geüploade bestand                     |
| `asset.fileSize`    | number         | Bestandsgrootte in bytes                                |
| `asset.type`        | string         | Afgeleid asset-type, bijv. `image`, `document`          |
| `asset.folderId`    | string \| null | Map waarin de asset is geplaatst, indien van toepassing |

## Statuscodes

| Status | Beschrijving                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------ |
| 200    | Succes - Asset geüpload                                                                                      |
| 400    | `chatId` of `file` ontbreekt, ongeldige JSON in `metadata`, of zowel `folderId` als `folderPath` meegestuurd |
| 401    | Ongeldige of ontbrekende API-sleutel                                                                         |
| 403    | API-sleutel heeft geen toegang tot deze chat                                                                 |
| 404    | Map niet gevonden                                                                                            |
| 413    | Bestand overschrijdt de limiet van 20 MB                                                                     |
| 500    | Serverfout                                                                                                   |

## Mapregels

* Mappaden worden gesplitst op `/`, getrimd, en lege segmenten worden genegeerd.
* De maximale diepte is 8 mappen.
* Elke mapnaam mag tot 255 tekens lang zijn.
* Het matchen van mappen is niet hoofdlettergevoelig binnen dezelfde bovenliggende map.
* Als `folderPath` niet bestaat en `createFolders` niet `true` is, mislukt de upload met een foutmelding 404.

## Goed om te weten

* Dit endpoint gebruikt dezelfde API-sleutel `macaly_...` als de rest van de API, ook al begint de URL met `/api/client-app/`. Er is geen apart token nodig.
* De chat waarnaar `chatId` verwijst, moet tot hetzelfde team behoren als uw API-sleutel.
* Geüploade assets krijgen een permanente CDN-URL die u kunt gebruiken als bijlage in [Chat aanmaken](/docs/nl/api/create-chat) of [Bericht publiceren](/docs/nl/api/publish-message), of overal buiten Macaly.