Media#

POST /api/uploadFile#

Upload a file via multipart/form-data and receive metadata plus the URL to reference in a photo or file attachment.

No envelope

Unlike every other endpoint, uploadFile returns its JSON payload directly (no { ok, result } wrapper), and errors as plain text with the matching HTTP status.

Request#

Content-Type: multipart/form-data
A single field named file carries the bytes. Other fields are ignored.
Maximum size is 10 MB; larger uploads return 413.

curl -X POST http://localhost:4000/api/uploadFile \
  -H "authorization: Bearer dev:ops" \
  -F "file=@chart.png"

Response#

{
  "media_id": "5f2c9b7a-…",
  "url": "/media/5f2c9b7a-….png",
  "mime": "image/png",
  "size_bytes": 48211,
  "filename": "chart.png"
}

Field	Type	Description
`media_id`	string	Stable id for the stored file.
`url`	string	Path to the file, served from `/media/<id>`. Use this in attachments.
`mime`	string	Declared or guessed content type.
`size_bytes`	integer	File size.
`filename`	string?	Original filename, when provided.

Using the result#

Reference the media_id and url in a photo or file attachment when calling sendMessage:

{
  "chat_id": "0d6c…",
  "text": "Here's the chart",
  "attachments": [
    {
      "kind": "photo",
      "id": "att-1",
      "media_id": "5f2c9b7a-…",
      "url": "/media/5f2c9b7a-….png",
      "w": 1200,
      "h": 800
    }
  ]
}

Errors#

Status	When
`400`	No `file` field, or malformed multipart.
`413`	File exceeds 10 MB.
`500`	Failed to write the file on the server.