Upload asset
Endpoints
Upload asset
Upload a file to a chat and get a permanent CDN URL
POST
Upload asset
Uploads a file to a chat’s Assets and returns a permanent CDN URL. Use this for images, documents, audio, video, or any other file you want your app or workflow to reference by URL.
Request
Headers
Form Data Parameters
Provide either
folderId or folderPath, not both. Sending both returns a 400 error.Example Request
Uploading into a folder
UsefolderPath for a human-readable folder structure, and set createFolders=true to create any missing folders along the path:
cURL
Response
Status Codes
Folder rules
- Folder paths are split on
/, trimmed, and empty segments are ignored. - Maximum depth is 8 folders.
- Each folder name can be up to 255 characters.
- Folder matching is case-insensitive within the same parent.
- If
folderPathdoesn’t exist andcreateFoldersisn’ttrue, the upload fails with a 404.
Good to know
- This endpoint uses the same
macaly_...API key as the rest of the API, even though the URL starts with/api/client-app/. No separate token is needed. - The chat referenced by
chatIdmust belong to the same team as your API key. - Uploaded assets get a permanent CDN URL you can reference in Create chat or Publish message as an attachment, or use anywhere outside Macaly.