Skip to main content
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

Use folderPath 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 folderPath doesn’t exist and createFolders isn’t true, 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 chatId must 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.