Upload message images
POST
https://sgtr-integration.returning.ai/apis/v1/messages/upload-image
Messaging
What this endpoint does
multipart/form-data with the field name images.{} is not a valid body.INFO
sendMessage → POST /v1/messages/upload-image as multipart images → save returned url values → pass them into send message.Quick start
images field to upload more than one file.Authentication and permission
Authorization: Bearer <COMMUNITY_API_KEY>. Required permission is sendMessage. Keep the key server-side.Complete examples
Content-Type: application/json with {} returns { "status": "error", "message": "No image buffers provided" }.images returns a top-level array:[
{
"id": "<uploadId>",
"name": "pixel.png",
"url": "https://files.example.com/pixel.png",
"type": "image/png",
"size": 67
}
]url as opaque. Do not hard-code a storage hostname in clients. Treat filenames as synthetic.Success and readback
200. The body is a raw array, not { status, data }.id, name, url, type, and size. Persist url if a later send-message call needs it. There is no follow-up GET for the upload record.CHECK
200 array with a url means the bytes were accepted. Sending the message is a separate call. If send fails, the uploaded file can still exist.Errors and recovery
| Status | When | Recovery |
|---|---|---|
400 No image buffers provided | JSON body, missing files, or empty multipart | Send multipart/form-data with images. |
401 | Missing or invalid Bearer token | Add a valid community key with sendMessage. |
Retry safety
WARNING
url already returned. There is no idempotency key. Duplicate successful uploads create additional stored objects.Gotchas
images, not file or csv.Next steps
Request
Body Params multipart/form-data
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://sgtr-integration.returning.ai/apis/v1/messages/upload-image' \
--form 'images=@""'Response Response Example
200 - Example 1
[
{
"id": "string",
"name": "string",
"url": "string",
"type": "string",
"size": 0
}
]Modified at 2026-08-19 03:29:16