Media
The image library: multipart upload, folders, and the read that serves a stored file transformed on the fly — w, h, crop, q and fmt are the whole vocabulary, and it is the same URL a rendered site fetches.
Get media
Serves a stored file, transformed on the fly. w and h fit the image inside a box; add crop=1 to fill the box exactly and centre-crop the overflow; q sets the quality and fmt the output format. Every variant is derived from the original and cached, so asking for the size you will display costs nothing extra and is what a rendered page already does.
This is the one route of the engine surface the platform publishes, and it is unauthenticated by design: it is the URL a browser fetches from a public page.
path Parameters
website_idId of the parent website.
idId of the media resource this URL addresses.
query Parameters
wTarget width in pixels (max 4096).
hTarget height in pixels (max 4096).
cropOutput exactly w×h, centre-cropping the overflow, instead of fitting inside the box. Needs both dimensions; only 1 and true enable it.
qOutput quality, 1–100.
fmtOutput format. Defaults to the stored format.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get media › Responses
The stored bytes.
List media
A file in the website's media library. Create is a multipart/form-data upload — everything but alt_text, title and folder_id is read off the file itself — and the bytes come back from GET /engine-api/v1/websites/{website_id}/media/{id}, which resizes and re-encodes on the fly — the same URL a rendered page asks for.
path Parameters
website_idId of the parent website.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, filename, folder_id, is_image, mime_type, original_filename.
filterAIP-160 subset (§8). Filterable: alt_text, create_time, filename, folder_id, is_image, mime_type, original_filename, title. A field outside the list is INVALID_ARGUMENT.
List media › Responses
One page of media.
This page of media, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create media
A file in the website's media library. Create is a multipart/form-data upload — everything but alt_text, title and folder_id is read off the file itself — and the bytes come back from GET /engine-api/v1/websites/{website_id}/media/{id}, which resizes and re-encodes on the fly — the same URL a rendered page asks for.
path Parameters
website_idId of the parent website.
Create media › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
filenameThe name the file is stored under, made unique on upload. This is the one that appears in the URL.
original_filenameThe name the file arrived with, kept so a person can recognise their own upload.
mime_typeThe stored file's media type, detected on upload. filter=mime_type:"image/" is how you ask for pictures by family.
storage_pathWhere the bytes live in the platform's object store. Internal bookkeeping — fetch the file through its media URL, not through this.
file_sizeSize of the stored original, in bytes. A transformed variant is smaller and is not counted here.
is_imageWhether the file is an image, and therefore whether the w/h/crop/q/fmt transforms apply to it.
widthWidth of the stored original in pixels. Meaningful only when is_image is true.
heightHeight of the stored original in pixels. Meaningful only when is_image is true.
alt_textThe alternative text rendered with the picture. It is what a screen reader announces, so it belongs on every image that carries meaning.
titleA human label for the file in the media library.
folder_idThe media_folders resource this file sits in. filter=folder_id = null is the library's root.
Get media
A file in the website's media library. Create is a multipart/form-data upload — everything but alt_text, title and folder_id is read off the file itself — and the bytes come back from GET /engine-api/v1/websites/{website_id}/media/{id}, which resizes and re-encodes on the fly — the same URL a rendered page asks for.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get media › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
filenameThe name the file is stored under, made unique on upload. This is the one that appears in the URL.
original_filenameThe name the file arrived with, kept so a person can recognise their own upload.
mime_typeThe stored file's media type, detected on upload. filter=mime_type:"image/" is how you ask for pictures by family.
storage_pathWhere the bytes live in the platform's object store. Internal bookkeeping — fetch the file through its media URL, not through this.
file_sizeSize of the stored original, in bytes. A transformed variant is smaller and is not counted here.
is_imageWhether the file is an image, and therefore whether the w/h/crop/q/fmt transforms apply to it.
widthWidth of the stored original in pixels. Meaningful only when is_image is true.
heightHeight of the stored original in pixels. Meaningful only when is_image is true.
alt_textThe alternative text rendered with the picture. It is what a screen reader announces, so it belongs on every image that carries meaning.
titleA human label for the file in the media library.
folder_idThe media_folders resource this file sits in. filter=folder_id = null is the library's root.
Delete media
A file in the website's media library. Create is a multipart/form-data upload — everything but alt_text, title and folder_id is read off the file itself — and the bytes come back from GET /engine-api/v1/websites/{website_id}/media/{id}, which resizes and re-encodes on the fly — the same URL a rendered page asks for.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete media › Responses
Deleted. No body (§7).
Update media
A file in the website's media library. Create is a multipart/form-data upload — everything but alt_text, title and folder_id is read off the file itself — and the bytes come back from GET /engine-api/v1/websites/{website_id}/media/{id}, which resizes and re-encodes on the fly — the same URL a rendered page asks for.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update media › Request Body
alt_textThe alternative text rendered with the picture. It is what a screen reader announces, so it belongs on every image that carries meaning.
titleA human label for the file in the media library.
folder_idThe media_folders resource this file sits in. filter=folder_id = null is the library's root.
Update media › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
filenameThe name the file is stored under, made unique on upload. This is the one that appears in the URL.
original_filenameThe name the file arrived with, kept so a person can recognise their own upload.
mime_typeThe stored file's media type, detected on upload. filter=mime_type:"image/" is how you ask for pictures by family.
storage_pathWhere the bytes live in the platform's object store. Internal bookkeeping — fetch the file through its media URL, not through this.
file_sizeSize of the stored original, in bytes. A transformed variant is smaller and is not counted here.
is_imageWhether the file is an image, and therefore whether the w/h/crop/q/fmt transforms apply to it.
widthWidth of the stored original in pixels. Meaningful only when is_image is true.
heightHeight of the stored original in pixels. Meaningful only when is_image is true.
alt_textThe alternative text rendered with the picture. It is what a screen reader announces, so it belongs on every image that carries meaning.
titleA human label for the file in the media library.
folder_idThe media_folders resource this file sits in. filter=folder_id = null is the library's root.
List media_folders
A folder of the media library. Folders are a tree: parent_id names the one above, path, level and sort_order are maintained by the server, and the shape is changed with :move rather than by writing those fields. A file's folder is the folder_id on the file itself.
path Parameters
website_idId of the parent website.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: path asc. Sortable: display_name, level, parent_id, path, sort_order.
filterAIP-160 subset (§8). Filterable: display_name, level, parent_id, path. A field outside the list is INVALID_ARGUMENT.
List media_folders › Responses
One page of media_folders.
This page of media_folders, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create media_folder
A folder of the media library. Folders are a tree: parent_id names the one above, path, level and sort_order are maintained by the server, and the shape is changed with :move rather than by writing those fields. A file's folder is the folder_id on the file itself.
path Parameters
website_idId of the parent website.
Create media_folder › Request Body
display_nameThe folder's name, as the media library shows it.
parent_idThe folder this one sits in; empty at the root. Settable on create and immutable afterwards — moving a folder is :move.
Create media_folder › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe folder's name, as the media library shows it.
parent_idThe folder this one sits in; empty at the root. Settable on create and immutable afterwards — moving a folder is :move.
pathThe folder's position in the tree, as the ids of its ancestors and its own. Sorting by it renders the whole tree in one page, which is why it is the default order.
sort_orderThe folder's position among its siblings. Set by :move, never by a write.
levelHow deep the folder sits, counting the root as 0. Server-maintained with the rest of the tree bookkeeping.
Get media_folder
A folder of the media library. Folders are a tree: parent_id names the one above, path, level and sort_order are maintained by the server, and the shape is changed with :move rather than by writing those fields. A file's folder is the folder_id on the file itself.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get media_folder › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe folder's name, as the media library shows it.
parent_idThe folder this one sits in; empty at the root. Settable on create and immutable afterwards — moving a folder is :move.
pathThe folder's position in the tree, as the ids of its ancestors and its own. Sorting by it renders the whole tree in one page, which is why it is the default order.
sort_orderThe folder's position among its siblings. Set by :move, never by a write.
levelHow deep the folder sits, counting the root as 0. Server-maintained with the rest of the tree bookkeeping.
Delete media_folder
A folder of the media library. Folders are a tree: parent_id names the one above, path, level and sort_order are maintained by the server, and the shape is changed with :move rather than by writing those fields. A file's folder is the folder_id on the file itself.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete media_folder › Responses
Deleted. No body (§7).
Update media_folder
A folder of the media library. Folders are a tree: parent_id names the one above, path, level and sort_order are maintained by the server, and the shape is changed with :move rather than by writing those fields. A file's folder is the folder_id on the file itself.
path Parameters
website_idId of the parent website.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update media_folder › Request Body
display_nameThe folder's name, as the media library shows it.
Update media_folder › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe folder's name, as the media library shows it.
parent_idThe folder this one sits in; empty at the root. Settable on create and immutable afterwards — moving a folder is :move.
pathThe folder's position in the tree, as the ids of its ancestors and its own. Sorting by it renders the whole tree in one page, which is why it is the default order.
sort_orderThe folder's position among its siblings. Set by :move, never by a write.
levelHow deep the folder sits, counting the root as 0. Server-maintained with the rest of the tree bookkeeping.
Move (media_folders)
Moves a folder inside the library's tree. Send {"parent_id": ..., "after_id": ...}: parent_id absent or null means the root, after_id absent or null means first among its new siblings. The move is what rewrites path, level and sort_order, which is why parent_id is immutable on Update.
path Parameters
website_idId of the parent website.
idId of the media_folders resource this URL addresses.
Move (media_folders) › Request Body optional
Move (media_folders) › Responses
The affected resource, or the method’s own response object (§10).