> ## 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.

# Upload asset

> Lade eine Datei zu einem Chat hoch und erhalte eine permanente CDN-URL

Lädt eine Datei in die Assets eines Chats hoch und gibt eine permanente CDN-URL zurück. Nutze das für Bilder, Dokumente, Audio, Video oder jede andere Datei, die deine App oder dein Prozess per URL referenzieren soll.

## Anfrage

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

### Header

| Header | Erforderlich | Beschreibung |
| - | - | - |
| `Authorization` | Ja | `Bearer macaly_...` |
| `Content-Type` | Ja | `multipart/form-data` |

### Form-Data-Parameter

| Feld | Typ | Erforderlich | Standardwert | Beschreibung |
| - | - | - | - | - |
| `chatId` | string | Ja | - | Der Chat, zu dem das Asset hochgeladen wird |
| `file` | file | Ja | - | Die hochzuladende Datei. Maximalgröße 20 MB |
| `folderPath` | string | Nein | - | Ordnerpfad mit Schrägstrichen getrennt, z. B. `images/products` |
| `createFolders` | string | Nein | `false` | `"true"`, `"1"` oder `"yes"` erstellt fehlende Ordner in `folderPath` |
| `folderId` | string | Nein | - | ID eines bestehenden Ordners. Sende nicht gleichzeitig `folderId` und `folderPath` |
| `title` | string | Nein | Ursprünglicher Dateiname | Anzeigetitel für das Asset |
| `metadata` | string (JSON) | Nein | - | JSON-Objekt, das zusammen mit dem Asset gespeichert wird |

<Note>
  Gib entweder `folderId` oder `folderPath` an, nicht beides. Wenn beide gesendet werden, kommt ein 400-Fehler zurück.
</Note>

### Beispielanfrage

<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>

### In einen Ordner hochladen

Nutze `folderPath` für eine lesbare Ordnerstruktur und setze `createFolders=true`, um fehlende Ordner im Pfad zu erstellen:

```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"
```

## Antwort

```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"
  }
}
```

| Feld | Typ | Beschreibung |
| - | - | - |
| `asset.assetId` | string | Eindeutige Kennung des Assets |
| `asset.url` | string | Permanente CDN-URL für die hochgeladene Datei |
| `asset.storageKey` | string | Interner Speicherpfad |
| `asset.contentType` | string | MIME-Typ der hochgeladenen Datei |
| `asset.fileSize` | number | Dateigröße in Bytes |
| `asset.type` | string | Ermittelter Asset-Typ, z. B. `image`, `document` |
| `asset.folderId` | string \| null | Ordner, in dem das Asset abgelegt wurde, falls vorhanden |

## Statuscodes

| Status | Beschreibung |
| - | - |
| 200 | Erfolgreich - Asset hochgeladen |
| 400 | `chatId` oder `file` fehlt, ungültiges `metadata`-JSON, oder sowohl `folderId` als auch `folderPath` angegeben |
| 401 | Ungültiger oder fehlender API-Schlüssel |
| 403 | API-Schlüssel hat keinen Zugriff auf diesen Chat |
| 404 | Ordner nicht gefunden |
| 413 | Datei überschreitet das Upload-Limit von 20 MB |
| 500 | Serverfehler |

## Ordnerregeln

* Ordnerpfade werden an `/` getrennt, getrimmt, und leere Segmente werden ignoriert.
* Die maximale Tiefe beträgt 8 Ordner.
* Jeder Ordnername darf bis zu 255 Zeichen lang sein.
* Der Ordnerabgleich unterscheidet innerhalb desselben übergeordneten Ordners nicht zwischen Groß- und Kleinschreibung.
* Existiert `folderPath` nicht und `createFolders` ist nicht `true`, schlägt der Upload mit 404 fehl.

## Gut zu wissen

* Dieser Endpoint verwendet denselben `macaly_...`-API-Schlüssel wie der Rest der API, auch wenn die URL mit `/api/client-app/` beginnt. Es wird kein separates Token benötigt.
* Der über `chatId` referenzierte Chat muss zum selben Team gehören wie dein API-Schlüssel.
* Hochgeladene Assets erhalten eine permanente CDN-URL, die du in [Create chat](/docs/de/api/create-chat) oder [Publish message](/docs/de/api/publish-message) als Anhang referenzieren oder auch außerhalb von Macaly verwenden kannst.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.