Skip to main content
POST
Describe a media file

Authorizations

Authorization
string
header
required

Supabase JWT — Authorization: Bearer <token>.

Body

application/json
media_id
string<uuid>
required

The file to change.

Minimum string length: 1
action
enum<string>

update (default) changes the fields you send. delete deletes the file: send only media_id. It is refused with 409 while a page, brand, CSS file, style setting, company logo or branding, interview, position, blog post, avatar or coaching catalogue uses it (the answer lists what does); it cannot be undone.

Available options:
update,
delete
Example:

"update"

file_name
string

Display name in the library.

Example:

"team-photo.jpg"

folder
string

Move the file to this folder; "" is the top. The file gets a new address in that folder; the old address keeps working for published pages, and page drafts move to the new one.

Example:

"team"

alt
object

Alt text per language code. Replaces the whole set, so send every language.

Example:
focal_x
number | null

Horizontal focal point, 0 (left) to 1 (right). Null clears it.

Required range: 0 <= x <= 1
Example:

0.5

focal_y
number | null

Vertical focal point, 0 (top) to 1 (bottom). Null clears it.

Required range: 0 <= x <= 1
Example:

0.3

poster_url
string | null

Still image shown before a video plays: the url of an image in this company's library. Null removes it.

Response

The file as it is now; for action: "delete", the deleted file's id and status.

id
string
required

Id of the file (media_id).

Example:

"c9d6f121-1230-48fd-b3a7-8b5a1e8db052"

status
string
required

The file's status; deleted after action delete (the stored objects go shortly after, in the background).

merchant_id
string

Company whose library holds the file.

kind
enum<string>

image, video, audio or font.

Available options:
image,
video,
audio,
font
file_name
string

Display name in the library.

Example:

"team-photo.jpg"

folder
string

Library folder; "" is the top. It is the directory of the file in storage.

Example:

"team"

path
string

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

url
string

Public address of the file, served by the CDN. It changes when the file is replaced.

content_type
string

Content type of the file.

Example:

"image/jpeg"

size_bytes
integer

Size of the file in bytes, measured after the upload.

width
integer | null

Width in pixels, as sent to media-upload-finish.

height
integer | null

Height in pixels, as sent to media-upload-finish.

duration_seconds
number | null

Length of a video or audio file in seconds, as sent to media-upload-finish.

poster_url
string | null

Still image shown before a video plays.

alt
object

Alt text per language code, such as {"en": "Our team"}.

focal_x
number | null

Horizontal focal point, 0 (left) to 1 (right).

focal_y
number | null

Vertical focal point, 0 (top) to 1 (bottom).

version
integer

Goes up each time the file is replaced.

read_only
boolean

True for a file of the parent company's library: it can be used on pages but not changed or deleted.

created_at
string
updated_at
string
drafts_updated
integer

Page drafts moved to the new address when the file changed folder; 0 otherwise. Published pages keep the old address until they are published again.

warnings
string[]

Things worth telling the person. The change was made.