Skip to main content
POST
Start uploading a media file

Authorizations

Authorization
string
header
required

Supabase JWT — Authorization: Bearer <token>.

Body

application/json
file_name
string
required

Display name in the library. It is never part of the address.

Example:

"team-photo.jpg"

content_type
enum<string>
required

Type of the file: image/jpeg, image/png, image/webp, image/gif, image/avif, image/svg+xml, video/mp4, audio/mpeg, audio/mp4, audio/x-m4a, font/woff2. Video must be H.264 MP4. Upload the file with this same content type.

Available options:
image/jpeg,
image/png,
image/webp,
image/gif,
image/avif,
image/svg+xml,
video/mp4,
audio/mpeg,
audio/mp4,
audio/x-m4a,
font/woff2
Example:

"image/jpeg"

size_bytes
integer
required

Size of the file in bytes, at most 52428800 (50 MB). A larger file answers 413.

Required range: x > 0
Example:

120000

merchant_id
string<uuid>

Optional company to upload for. Admins and sub-merchant operators only; other callers always use their token's company.

Example:

"28106cba-1c27-4e53-b149-32113e5e8e31"

folder
string

Library folder to upload into; default the top (""). The folder need not exist yet. Ignored when replacing: a new version stays in the folder of the file.

Example:

"team"

replace_media_id
string<uuid>

Replace this file instead of adding one. Must be the same kind. The file keeps its id, name and alt text and gets a new address when media-upload-finish accepts it.

Minimum string length: 1

Response

Where to upload the file.

media_id
string
required

Send this to media-upload-finish after the upload.

upload_url
string
required

Signed address, valid for two hours. PUT the file here with the Content-Type you declared and Cache-Control: max-age=<cache_control>.

token
string
required

The token inside upload_url, for clients that upload with the Supabase library (uploadToSignedUrl).

path
string
required

Object name in the public bucket: <merchant_id>/[/]<media_id>-v..

cache_control
integer
required

Seconds to send as the cache lifetime: a file name is never reused, so a year is safe.

Example:

31536000