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

> Caricamento di un file in una chat e ottenimento di una URL CDN permanente

Carica un file nelle Risorse di una chat e restituisce una URL CDN permanente. Usalo per immagini, documenti, audio, video o qualsiasi altro file che la tua app o la tua elaborazione deve richiamare tramite URL.

## Richiesta

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

### Header

| Header | Obbligatorio | Descrizione |
| - | - | - |
| `Authorization` | Sì | `Bearer macaly_...` |
| `Content-Type` | Sì | `multipart/form-data` |

### Parametri del form data

| Campo | Tipo | Obbligatorio | Predefinito | Descrizione |
| - | - | - | - | - |
| `chatId` | string | Sì | - | La chat in cui caricare la risorsa |
| `file` | file | Sì | - | Il file da caricare. Dimensione massima 20 MB |
| `folderPath` | string | No | - | Percorso della cartella separato da barre, ad esempio `images/products` |
| `createFolders` | string | No | `false` | Con `"true"`, `"1"` o `"yes"` crea le cartelle mancanti in `folderPath` |
| `folderId` | string | No | - | ID di una cartella esistente. Non inviare insieme `folderId` e `folderPath` |
| `title` | string | No | Nome del file originale | Titolo visualizzato della risorsa |
| `metadata` | string (JSON) | No | - | Oggetto JSON memorizzato insieme alla risorsa |

<Note>
  Indica `folderId` oppure `folderPath`, non entrambi. Inviarli insieme restituisce un errore 400.
</Note>

### Esempio di richiesta

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

### Caricamento in una cartella

Usa `folderPath` per una struttura di cartelle leggibile e imposta `createFolders=true` per creare le cartelle mancanti lungo il percorso:

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

## Risposta

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

| Campo | Tipo | Descrizione |
| - | - | - |
| `asset.assetId` | string | Identificatore univoco della risorsa |
| `asset.url` | string | URL CDN permanente del file caricato |
| `asset.storageKey` | string | Percorso di archiviazione interno |
| `asset.contentType` | string | Tipo MIME del file caricato |
| `asset.fileSize` | number | Dimensione del file in byte |
| `asset.type` | string | Tipo di risorsa dedotto, ad esempio `image`, `document` |
| `asset.folderId` | string \| null | Cartella in cui è stata inserita la risorsa, se presente |

## Codici di stato

| Codice | Descrizione |
| - | - |
| 200 | Operazione riuscita: risorsa caricata |
| 400 | `chatId` o `file` mancante, JSON di `metadata` non valido oppure `folderId` e `folderPath` inviati insieme |
| 401 | Chiave API non valida o mancante |
| 403 | La chiave API non ha accesso a questa chat |
| 404 | Cartella non trovata |
| 413 | Il file supera il limite di caricamento di 20 MB |
| 500 | Errore del server |

## Regole per le cartelle

* I percorsi delle cartelle vengono divisi in corrispondenza di `/`, ripuliti dagli spazi superflui e i segmenti vuoti vengono ignorati.
* La profondità massima è di 8 cartelle.
* Ogni nome di cartella può contenere fino a 255 caratteri.
* All'interno della stessa cartella superiore la corrispondenza dei nomi non distingue tra maiuscole e minuscole.
* Se `folderPath` non esiste e `createFolders` non è `true`, il caricamento fallisce con un errore 404.

## Informazioni utili

* Questo endpoint usa la stessa chiave API `macaly_...` del resto dell'API, anche se la URL inizia con `/api/client-app/`. Non serve un token separato.
* La chat indicata da `chatId` deve appartenere allo stesso team della tua chiave API.
* Le risorse caricate ottengono una URL CDN permanente che puoi indicare come allegato in [Create chat](/docs/it/api/create-chat) o [Publish message](/docs/it/api/publish-message), oppure usare ovunque al di fuori di Macaly.


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