Operazioni sui media
11 operazioni di nome media.*. Ognuna si esegue in un batch con apply_ops, dry_run_ops, la CLI o l’admin.
| 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.
Esempio di 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. |
I campi più annidati sono nello schema di output che risponde discover_operations con outputSchemas: true.
Provala
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.
Esempio di 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 |
Provala
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.
Esempio di 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. |
Provala
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.
Esempio di 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. |
Provala
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.
Esempio di 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. |
Provala
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.
Esempio di input
{
"mediaId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| success | true | yes |
Vuole confirmed: ["destructive"] sul batch, che la forma della CLI per una sola operazione non imposta: mettila in un file di batch ed esegui 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.
Esempio di 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. |
Provala
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.
Esempio di 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. |
Provala
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.
Esempio di 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. |
Provala
yarn splash media.createFolder '{"name":"Projects","parentId":null}' --dry-runmedia.renameFolder
Rename a media folder. Site ownership is checked; undo restores the media ledger.
Esempio di 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. |
Provala
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.
Esempio di input
{
"folderId": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a"
}Input
| Field | Type | Required | Notes |
|---|---|---|---|
| folderId | string (uuid) | yes |
Output
| Field | Type | Required | Notes |
|---|---|---|---|
| success | true | yes |
Vuole confirmed: ["destructive"] sul batch, che la forma della CLI per una sola operazione non imposta: mettila in un file di batch ed esegui yarn splash apply <file> --dry-run.
Generato dal registro delle operazioni e dal catalogo degli strumenti MCP (sorgente 0eff2e5995d25e02).
Qualcosa non va in questa pagina? Scrivi a docs@librettocms.com.