Skip to content
mondochat

Request an upload

POST
/v1/photos/uploads
curl --request POST \
  --url https://app.mondochat.io/v1/photos/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "bytes": 482113, "content_type": "image/jpeg", "conversation_id": "0199d6a0-2000-7000-8000-000000000001" }'

Creates a pending photo, video or voice note and returns a presigned POST that lives 5 minutes. Send the file to it, then call the complete route. Takes a session token. Policy photos, chat.photos, the daily limits, bans and safety apply, as does the receiver’s refusal of photos. video/mp4 answers 403 policy_denied with reason videos unless chat.videos is on, and audio/mp4 with reason voice unless chat.voice is on. A file above the size limit of its kind answers 422. See https://docs.mondochat.io/guides/media/.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
UploadRequest

Asks for a presigned upload of a photo, video or voice note into a conversation.

object
bytes
required
Bytes

The size of the file. Above chat.photo_max_bytes, chat.video_max_bytes or chat.voice_max_bytes for its kind the request answers 422.

integer
>= 1
content_type
required
Content Type

The media type you will upload. video/mp4 needs chat.videos and audio/mp4 needs chat.voice.

string
Allowed values: image/jpeg image/png image/webp image/heic video/mp4 audio/mp4
conversation_id
required
Conversation Id

The conversation the media is for.

string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
Upload

A presigned POST: send the file to url with fields as form fields.

object
expires_at
required
Expires At

When the upload link stops working, 5 minutes on.

string format: date-time
fields
required
Fields

Form fields to send with the file in the multipart POST.

object
key
additional properties
string
photo_id
required
Photo Id

The id of the pending media. Pass it to the complete route.

string format: uuid
url
required
Url

Where to POST the file.

string

Example 

{
  "expires_at": "2026-11-01T12:05:00Z",
  "fields": {
    "Content-Type": "image/jpeg",
    "key": "orig/p/0199d6a0-4000-7000-8000-000000000001/orig"
  },
  "photo_id": "0199d6a0-4000-7000-8000-000000000001",
  "url": "https://uploads.example.test/"
}

4XX

Section titled “4XX”

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object
code
required

The stable error code to branch on, such as policy_denied.

string
detail

What went wrong this time, when there is more to say.

string | null
errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object
loc

The path to the field.

array
msg

What is wrong with it.

string
instance

The path of the request.

string
reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string
status
required

The HTTP status code.

integer
title
required

A short summary of the problem.

string
type
required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example 

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}