Upload Agent App File

Upload a file for an Agent app conversation. Use the returned id as upload_file_id in the files array when calling Send Agent App Message. Uploaded files are scoped to the same user value.

POST /files/upload

Upload Agent App File

cURL

curl --request POST \
  --url https://{api_base_url}/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'user=<string>'

201

uploadSuccess

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "product-photo.png",
  "size": 204800,
  "extension": "png",
  "mime_type": "image/png",
  "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "created_at": 1705407629,
  "preview_url": null,
  "source_url": null,
  "original_url": null,
  "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "conversation_id": null,
  "file_key": "uploads/product-photo.png"
}

Authorizations

Authorization · string · header · required

API Key authentication. For all API requests, include your API Key in the Authorization HTTP Header, prefixed with Bearer. Example: Authorization: Bearer {API_KEY}. Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.

Body

multipart/form-data

File upload request. Requires multipart/form-data.

file · file · required

The file to be uploaded. Supported types include images, documents, audio, and video.

user · string · required

Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical.

Response

201

application/json

File uploaded successfully.

id · string<uuid>

Unique file ID.

name · string

File name.

size · integer

File size in bytes.

extension · string | null

File extension.

mime_type · string | null

MIME type of the file.

created_by · string<uuid> | null

ID of the user who uploaded the file.

created_at · integer<int64>

Upload timestamp (Unix epoch seconds).

preview_url · string | null

Preview URL for the file.

source_url · string | null

Source URL of the file.

original_url · string | null

Original URL of the file.

user_id · string<uuid> | null

ID of the associated user.

tenant_id · string<uuid> | null

ID of the associated tenant.

conversation_id · string<uuid> | null

ID of the associated conversation.

file_key · string | null

Storage key for the file.