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

> Ladda upp en fil till en chatt och få en permanent CDN-URL

Laddar upp en fil till en chatts filer (Assets) och returnerar en permanent CDN-URL. Använd den för bilder, dokument, ljud, video eller andra filer som din app eller ditt arbetsflöde ska referera till via URL.

## Anrop

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

### Headers

| Header | Obligatorisk | Beskrivning |
| - | - | - |
| `Authorization` | Ja | `Bearer macaly_...` |
| `Content-Type` | Ja | `multipart/form-data` |

### Formulärparametrar

| Fält | Typ | Obligatoriskt | Standardvärde | Beskrivning |
| - | - | - | - | - |
| `chatId` | string | Ja | - | Chatten som filen laddas upp till |
| `file` | file | Ja | - | Filen som ska laddas upp. Maxstorlek 20 MB |
| `folderPath` | string | Nej | - | Mappsökväg med snedstreck som avgränsare, till exempel `images/products` |
| `createFolders` | string | Nej | `false` | `"true"`, `"1"` eller `"yes"` skapar mappar som saknas i `folderPath` |
| `folderId` | string | Nej | - | ID för en befintlig mapp. Skicka inte både `folderId` och `folderPath` |
| `title` | string | Nej | Ursprungligt filnamn | Visningsnamn för filen |
| `metadata` | string (JSON) | Nej | - | JSON-objekt som sparas tillsammans med filen |

<Note>
  Ange antingen `folderId` eller `folderPath`, inte båda. Om du skickar båda returneras felet 400.
</Note>

### Exempelanrop

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

### Ladda upp till en mapp

Använd `folderPath` för en läsbar mappstruktur och sätt `createFolders=true` för att skapa mappar som saknas längs sökvägen:

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

## Svar

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

| Fält | Typ | Beskrivning |
| - | - | - |
| `asset.assetId` | string | Filens unika ID |
| `asset.url` | string | Permanent CDN-URL för den uppladdade filen |
| `asset.storageKey` | string | Intern lagringssökväg |
| `asset.contentType` | string | Den uppladdade filens MIME-typ |
| `asset.fileSize` | number | Filstorlek i byte |
| `asset.type` | string | Härledd filtyp, till exempel `image` eller `document` |
| `asset.folderId` | string \| null | Mappen som filen placerades i, om någon |

## Statuskoder

| Status | Beskrivning |
| - | - |
| 200 | Lyckades, filen laddades upp |
| 400 | `chatId` eller `file` saknas, `metadata` är ogiltig JSON, eller både `folderId` och `folderPath` har skickats |
| 401 | Ogiltig eller saknad API-nyckel |
| 403 | API-nyckeln har inte åtkomst till den här chatten |
| 404 | Mappen hittades inte |
| 413 | Filen överskrider uppladdningsgränsen på 20 MB |
| 500 | Serverfel |

## Regler för mappar

* Mappsökvägar delas upp vid `/`, mellanslag i början och slutet tas bort och tomma segment ignoreras.
* Maxdjupet är 8 mappar.
* Varje mappnamn får vara högst 255 tecken.
* Mappnamn matchas utan hänsyn till versaler och gemener inom samma överordnade mapp.
* Om `folderPath` inte finns och `createFolders` inte är `true` misslyckas uppladdningen med felet 404.

## Bra att veta

* Endpointen använder samma API-nyckel `macaly_...` som resten av API:t, även om URL:en börjar med `/api/client-app/`. Du behöver ingen separat token.
* Chatten som anges i `chatId` måste tillhöra samma team som din API-nyckel.
* Uppladdade filer får en permanent CDN-URL som du kan använda som bilaga i [Create chat](/docs/sv/api/create-chat) eller [Publish message](/docs/sv/api/publish-message), eller var som helst utanför Macaly.


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