Attachments: Send Files with Your Messages

Attachments let you upload files and include them in agent messages. Learn the three-step upload flow: request upload params, upload to storage, then mark complete.

Attachments are files (images, documents, and other media) that you can send alongside messages to the agent. The VyomFlow API uses a three-step upload flow so you can stream large files directly to storage without proxying them through the API.

Attachments are currently only available on the internal https://api.vyomflow.co.in/api/v1 surface, authenticated with a Clerk session token — there is no public, API-key-authenticated attachments endpoint under /api/public/v1 today. This page documents the first-party app’s own upload flow; an external/agent caller cannot currently attach files via the public API or MCP.

Upload flow

1. Request upload parameters

   Call the upload-params endpoint to receive a pre-signed storage URL and the fields you need for the next step.

   curl https://api.vyomflow.co.in/api/v1/attachments/upload-params \
     -H "Authorization: Bearer <clerk-session-token>"
   

   The response includes the storage URL, required form fields, and the attachmentId you will use later.

2. Upload the file

   PUT or POST the file bytes directly to the storage URL returned in step 1. This call goes to the storage provider, not the VyomFlow API, so do not include the Authorization: Bearer header here.

3. Mark the upload complete

   Once the file is in storage, tell the VyomFlow API the upload is finished so the attachment becomes usable.

   curl -X POST https://api.vyomflow.co.in/api/v1/attachments/att_abc123/complete \
     -H "Authorization: Bearer <clerk-session-token>"
   

Using an attachment in a message

After the upload is marked complete, reference the attachment by id in the message body when you send a message to a chat (POST /api/public/v1/chats/{chatId}/messages accepts the same attachments field).

{
  "content": [{ "type": "text", "text": "Please summarize this document." }],
  "attachments": [{ "id": "att_abc123" }]
}

The Attachment object

id · string

Unique identifier for the attachment, used in message bodies and API calls.

filename · string

Original name of the uploaded file.

contentType · string

MIME type of the file, for example image/png or application/pdf.

status · string

Current upload status. One of pending or complete.

createdAt · string

ISO 8601 timestamp when the attachment was created.

Next steps

• Send your first message with an attachment in the Quickstart
• Learn how chats and messages work in Chats