Returning.AIDevelopers
v1

API reference / Messaging

.md

Upload message images

Upload up to 10 image files and get a public URL for each, ready to attach to a message.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/messages/upload-image
Permission
sendMessage
Retries
Not idempotent; each retry uploads new copies

When to use this

  • Your system draws a chart as an image file and wants to post it in a channel.
  • Your images aren't online yet, so Send message can't fetch them from a URL.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
sendMessageShown in the dashboard as “Send Messages”

Use a Community API key with sendMessage, the same permission as Send message, and keep it on your server. A personal user API key with its own send permission also works.

Behaviour#

This call only stores the files; it doesn't post anything. Post them with Send message, passing the returned URLs in images.

The file type isn't checked, so send only images, and set each file part's content type, such as image/png. Uploaded files can't be deleted through the API.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with sendMessage.

RuleBearer <API_KEY>

Body#

Send the body as multipart/form-data with one images part per file, up to 10 files of up to 30 MB each.

images#fileREQUIRED
The image files. Repeat the images field once per file.

RuleUp to 10 files, 30 MB each

Send the body as multipart/form-data.

curl --request POST \
  --url https://api.returning.ai/v1/messages/upload-image \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'images=@xauusd-chart.png'

Response#

A 200 returns a JSON array with one entry per file, in the order you sent them, and no status or message. Keep each url for Send message.

id#string
An ID for this upload. It isn't used by other endpoints.
name#string
The file name you sent, or chart.png when the file part has no name.
url#string
The file's public URL. Pass it in images to Send message.
type#string
The content type you sent for the file, or image/png when none was given.
size#integer
The file size in bytes.
[
  {
    "id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
    "name": "xauusd-chart.png",
    "url": "https://cdn.example.com/uploads/xauusd-chart.png",
    "type": "image/png",
    "size": 48213
  }
]

Errors#

Errors have message, and sometimes status or detail. None has a machine-readable code, so branch on the HTTP status and read message.

Fix the request02

400Fix the request
No image buffers provided: the request had no files. Send them as multipart/form-data in the images field. Failed to upload 1 of 2 image(s): some files couldn't be stored; detail lists them, and none of the URLs is returned, so upload again.
401Fix the request
The key is missing (Invalid token), unknown (Invalid API key) or expired, or it lacks sendMessage (Your API key does not have permission to access this action). Add the permission in Settings > Integration > API Keys.

Retry with backoff01

500Retry with backoff
The upload failed, or the key could not be checked (Authentication failed). Retry the same request with backoff.
{
  "status": "error",
  "message": "No image buffers provided"
}

Next step#

Send messagePOST/v1/messages/sendPost the image in a channel by passing the returned url values in images.