Media operations
11 operations named media.*. Every one runs in a batch through apply_ops, dry_run_ops, the CLI or the admin.
Updated
| Operation | What it does | Permission | Confirmation |
|---|---|---|---|
| media.list | List the media library with its folders, filtered by folder, kind and filename. | site.read | none |
| media.usage | List where a media row is used: the draft and published page trees and the published articles that reference it, the pages and articles whose featured or social image it is, the design-system asset tokens and the site settings that name it. | site.read | none |
| media.recordUpload | Record a staged upload after re-inspecting its bytes: kind, dimensions, page count and variants. | content.edit | none |
| media.upload | Upload a file from its base64 bytes: staged, checked (type, size, magic, SVG sanitiser, quota), its variants rendered, then recorded like media.recordUpload, in its folder when one is named. | content.edit | none |
| media.replace | Replace the bytes of a media row with a staged upload, re-inspected like media.recordUpload (type, size, SVG sanitiser, variants, quota); the row keeps its id, alt text, caption, credit and folder, so every reference shows the new file. | content.edit | none |
| media.delete | Remove a media row from the library; its bytes stay for undo. | site.edit | destructive |
| media.update | Edit the alt text, caption, credit or folder of a media row. | content.edit | none |
| media.move | Move media rows into a folder, or to the top level with a null folder. | site.edit | none |
| media.createFolder | Create a media folder, at the top level or inside another folder. | site.edit | none |
| media.renameFolder | Rename a media folder. | site.edit | none |
| media.deleteFolder | Delete an empty media folder; a folder holding media or folders is refused. | site.edit | destructive |
media.list
List the media library with its folders, filtered by folder, kind and filename. Site ownership is checked; undo restores the media ledger.
permission: site.readreads onlyclass: read
Example input
{
"kinds": [
"image"
],
"perPage": 50
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| search | string | no | At most 200 characters. |
| page | integer | no | More than 0. |
| perPage | integer | no | At least 1. At most 100. |
| kinds | array of string | no | At least 1 item. At most 4 items. |
| folderId | string (uuid) | null | no |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| items | array of object | yes | |
| items[].id | string (uuid) | yes | |
| items[].kind | string | yes | One of "image", "svg", "video", "document". |
| items[].filename | string | yes | At least 1 character. At most 255 characters. |
| items[].mime | string | yes | At least 1 character. At most 127 characters. |
| items[].size | integer | yes | At least 0. |
| items[].url | string | yes | At least 1 character. At most 2048 characters. |
| items[].width | integer | no | At least 1. At most 100000. |
| items[].height | integer | no | At least 1. At most 100000. |
| items[].variants | array of object | yes | |
| items[].alt | string | record of string | yes | |
| items[].caption | string | record of string | no | |
| items[].credit | string | no | At most 200 characters. |
| items[].folderId | string (uuid) | null | no | |
| items[].pageCount | integer | no | At least 1. |
| items[].createdAt | string | yes | |
| total | number | yes | |
| page | number | yes | |
| perPage | number | yes | |
| usedBytes | number | yes | |
| quotaBytes | number | yes | |
| folders | array of object | yes | |
| folders[].id | string (uuid) | yes | |
| folders[].parentId | string (uuid) | null | yes | |
| folders[].name | string | yes | At least 1 character. At most 120 characters. |
Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.
Try it
yarn splash media.list '{"kinds":["image"],"perPage":50}' --dry-runmedia.usage
List where a media row is used: the draft and published page trees and the published articles that reference it, the pages and articles whose featured or social image it is, the design-system asset tokens and the site settings that name it. Site ownership is checked; undo restores the media ledger.
permission: site.readreads onlyclass: read
Example input
{
"mediaId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaId | string (uuid) | yes | |
| usages | array of object | object | object | yes |
Try it
yarn splash media.usage '{"mediaId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"}' --dry-runmedia.recordUpload
Record a staged upload after re-inspecting its bytes: kind, dimensions, page count and variants. Site ownership is checked; undo restores the media ledger.
permission: content.editwrites: mediaclass: transactionundo: yes
Example input
{
"filename": "studio.jpg",
"contentType": "image/jpeg",
"size": 482113,
"key": "staged/studio.jpg"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| filename | string | yes | At least 1 character. At most 255 characters. |
| contentType | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| key | string | yes | At least 1 character. At most 1024 characters. |
| folderId | string (uuid) | null | no |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| kind | string | yes | One of "image", "svg", "video", "document". |
| filename | string | yes | At least 1 character. At most 255 characters. |
| mime | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| url | string | yes | At least 1 character. At most 2048 characters. |
| width | integer | no | At least 1. At most 100000. |
| height | integer | no | At least 1. At most 100000. |
| variants | array of object | yes | |
| variants[].width | integer | yes | At least 1. At most 100000. |
| variants[].height | integer | no | At least 1. At most 100000. |
| variants[].mime | string | yes | One of "image/avif", "image/webp", "image/jpeg", "image/png". |
| variants[].url | string | yes | At least 1 character. At most 2048 characters. |
| variants[].bytes | integer | no | At least 0. |
| alt | string | record of string | yes | |
| caption | string | record of string | no | |
| credit | string | no | At most 200 characters. |
| folderId | string (uuid) | null | no | |
| pageCount | integer | no | At least 1. |
Try it
yarn splash media.recordUpload '{"filename":"studio.jpg","contentType":"image/jpeg","size":482113,"key":"staged/studio.jpg"}' --dry-runmedia.upload
Upload a file from its base64 bytes: staged, checked (type, size, magic, SVG sanitiser, quota), its variants rendered, then recorded like media.recordUpload, in its folder when one is named. The same limits as the admin upload (images 5 MB). Site ownership is checked; undo restores the media ledger.
permission: content.editwrites: mediaclass: transactionundo: yes
Example input
{
"filename": "studio.jpg",
"contentType": "image/jpeg",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| filename | string | yes | At least 1 character. At most 255 characters. |
| contentType | string | yes | At least 1 character. At most 127 characters. |
| data | string | yes | At least 1 character. At most 146800640 characters. |
| folderId | string (uuid) | null | no |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| kind | string | yes | One of "image", "svg", "video", "document". |
| filename | string | yes | At least 1 character. At most 255 characters. |
| mime | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| url | string | yes | At least 1 character. At most 2048 characters. |
| width | integer | no | At least 1. At most 100000. |
| height | integer | no | At least 1. At most 100000. |
| variants | array of object | yes | |
| variants[].width | integer | yes | At least 1. At most 100000. |
| variants[].height | integer | no | At least 1. At most 100000. |
| variants[].mime | string | yes | One of "image/avif", "image/webp", "image/jpeg", "image/png". |
| variants[].url | string | yes | At least 1 character. At most 2048 characters. |
| variants[].bytes | integer | no | At least 0. |
| alt | string | record of string | yes | |
| caption | string | record of string | no | |
| credit | string | no | At most 200 characters. |
| folderId | string (uuid) | null | no | |
| pageCount | integer | no | At least 1. |
Try it
yarn splash media.upload '{"filename":"studio.jpg","contentType":"image/jpeg","data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="}' --dry-runmedia.replace
Replace the bytes of a media row with a staged upload, re-inspected like media.recordUpload (type, size, SVG sanitiser, variants, quota); the row keeps its id, alt text, caption, credit and folder, so every reference shows the new file. The change is live: media is not versioned and published pages reference the row by id, so the published site shows the new file at once, without a publish. An image is replaced by an image or an SVG, a video by a video, a PDF by a PDF. Site ownership is checked; undo restores the media ledger.
permission: content.editwrites: mediaclass: transactionundo: yes
Example input
{
"mediaId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"filename": "studio-2.jpg",
"contentType": "image/jpeg",
"size": 501220,
"key": "staged/studio-2.jpg"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| filename | string | yes | At least 1 character. At most 255 characters. |
| contentType | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| key | string | yes | At least 1 character. At most 1024 characters. |
| mediaId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| kind | string | yes | One of "image", "svg", "video", "document". |
| filename | string | yes | At least 1 character. At most 255 characters. |
| mime | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| url | string | yes | At least 1 character. At most 2048 characters. |
| width | integer | no | At least 1. At most 100000. |
| height | integer | no | At least 1. At most 100000. |
| variants | array of object | yes | |
| variants[].width | integer | yes | At least 1. At most 100000. |
| variants[].height | integer | no | At least 1. At most 100000. |
| variants[].mime | string | yes | One of "image/avif", "image/webp", "image/jpeg", "image/png". |
| variants[].url | string | yes | At least 1 character. At most 2048 characters. |
| variants[].bytes | integer | no | At least 0. |
| alt | string | record of string | yes | |
| caption | string | record of string | no | |
| credit | string | no | At most 200 characters. |
| folderId | string (uuid) | null | no | |
| pageCount | integer | no | At least 1. |
Try it
yarn splash media.replace '{"mediaId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","filename":"studio-2.jpg","contentType":"image/jpeg","size":501220,"key":"staged/studio-2.jpg"}' --dry-runmedia.delete
Remove a media row from the library; its bytes stay for undo. Site ownership is checked; undo restores the media ledger.
permission: site.editwrites: mediaclass: transactionconfirm: destructiveundo: yes
Example input
{
"mediaId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| success | true | yes |
Needs confirmed: ["destructive"] on the batch, which the single-operation CLI form does not set: put it in a batch file and run yarn splash apply <file> --dry-run.
media.update
Edit the alt text, caption, credit or folder of a media row. Site ownership is checked; undo restores the media ledger.
permission: content.editwrites: mediaclass: transactionundo: yes
Example input
{
"mediaId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"alt": {
"en-US": "The studio courtyard at dusk"
},
"credit": "Studio archive"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaId | string (uuid) | yes | |
| alt | string | record of string | no | |
| caption | string | record of string | null | no | |
| credit | string | null | no | |
| folderId | string (uuid) | null | no |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| kind | string | yes | One of "image", "svg", "video", "document". |
| filename | string | yes | At least 1 character. At most 255 characters. |
| mime | string | yes | At least 1 character. At most 127 characters. |
| size | integer | yes | At least 0. |
| url | string | yes | At least 1 character. At most 2048 characters. |
| width | integer | no | At least 1. At most 100000. |
| height | integer | no | At least 1. At most 100000. |
| variants | array of object | yes | |
| variants[].width | integer | yes | At least 1. At most 100000. |
| variants[].height | integer | no | At least 1. At most 100000. |
| variants[].mime | string | yes | One of "image/avif", "image/webp", "image/jpeg", "image/png". |
| variants[].url | string | yes | At least 1 character. At most 2048 characters. |
| variants[].bytes | integer | no | At least 0. |
| alt | string | record of string | yes | |
| caption | string | record of string | no | |
| credit | string | no | At most 200 characters. |
| folderId | string (uuid) | null | no | |
| pageCount | integer | no | At least 1. |
Try it
yarn splash media.update '{"mediaId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","alt":{"en-US":"The studio courtyard at dusk"},"credit":"Studio archive"}' --dry-runmedia.move
Move media rows into a folder, or to the top level with a null folder. Site ownership is checked; undo restores the media ledger.
permission: site.editwrites: mediaclass: transactionundo: yes
Example input
{
"mediaIds": [
"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
],
"folderId": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaIds | array of string (uuid) | yes | At least 1 item. At most 200 items. |
| folderId | string (uuid) | null | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| moved | integer | yes | At least 0. |
Try it
yarn splash media.move '{"mediaIds":["2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"],"folderId":"3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a"}' --dry-runmedia.createFolder
Create a media folder, at the top level or inside another folder. Site ownership is checked; undo restores the media ledger.
permission: site.editwrites: mediaclass: transactionundo: yes
Example input
{
"name": "Projects",
"parentId": null
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | yes | At least 1 character. At most 120 characters. |
| parentId | string (uuid) | null | no |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| parentId | string (uuid) | null | yes | |
| name | string | yes | At least 1 character. At most 120 characters. |
Try it
yarn splash media.createFolder '{"name":"Projects","parentId":null}' --dry-runmedia.renameFolder
Rename a media folder. Site ownership is checked; undo restores the media ledger.
permission: site.editwrites: mediaclass: transactionundo: yes
Example input
{
"folderId": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a",
"name": "Built projects"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| folderId | string (uuid) | yes | |
| name | string | yes | At least 1 character. At most 120 characters. |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string (uuid) | yes | |
| parentId | string (uuid) | null | yes | |
| name | string | yes | At least 1 character. At most 120 characters. |
Try it
yarn splash media.renameFolder '{"folderId":"3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a","name":"Built projects"}' --dry-runmedia.deleteFolder
Delete an empty media folder; a folder holding media or folders is refused. Site ownership is checked; undo restores the media ledger.
permission: site.editwrites: mediaclass: transactionconfirm: destructiveundo: yes
Example input
{
"folderId": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| folderId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| success | true | yes |
Needs confirmed: ["destructive"] on the batch, which the single-operation CLI form does not set: put it in a batch file and run yarn splash apply <file> --dry-run.
Generated from the operation registry and the MCP tool catalogue (source 0eff2e5995d25e02).
Something wrong on this page? Write to docs@librettocms.com.