Media
Upload, import, organize and archive images and videos.
List the media library
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
folderId | string | Optional | Folder. |
kind | string | Optional | image, video, document or audio, or several comma-separated; without one, images and videos. |
status | string | Optional | Processing status. |
q | string | Optional | Search. |
usage | string | Optional | used or unused. |
archived | string | Optional | exclude (default), include or only. Archived media still counts toward media storage until deleted. |
sort | string | Optional | newest (default), oldest, name, size (largest first), usage (in the most launches first) or least_used. |
tags | string | Optional | Tag (workflow label) IDs, comma-separated, up to 50: only files used by an ad that isn't archived and has any of them. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].archivedAt- Archived; still counted toward media storage until deleted.
items[].byteSize- Size in bytes.
items[].contentType- MIME type.
items[].createdAt- Added.
items[].createdBy- Their ID.
items[].createdByKind- Who added it.One of
person,api_key,agent,system items[].deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].durationMs- Videos and audio files: duration.
items[].error- Why processing failed.
items[].errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].errorParams- The values
errorCode's sentence names, present exactly when it is. items[].folderId- Folder; null for the library root.
items[].hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].height- Pixels, once processed.
items[].id- ID.
items[].kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].name- Name.
items[].pageCount- Documents: pages, once processed.
items[].processedAt- Processed.
items[].sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].sourceUrl- Where an import came from.
items[].status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].updatedAt- Last change.
items[].version- Increments on every change; send as
expectedVersion. items[].warnings- Provider-spec findings that don't block use.
items[].warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].warnings[].message- Finding.
items[].warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].width- Pixels, once processed.
items[].launchCount- Launches whose ads use it.
items[].previewUrl- Short-lived thumbnail URL (a video's poster frame).
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/media" \
-H "Authorization: Bearer $PLUTO_KEY"Archive media
One command with a changeset; an outcome per item. Ads already using archived media keep working.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- 1 to 1000 distinct media.
items[].expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
items[].id- Media.
Response
changesetId- The change record; null when nothing changed.
items- One outcome per item:
mediawhen accepted,errors(andreason,launches) when rejected,currenton a version conflict. items[].current- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAt- Archived; still counted toward media storage until deleted.
items[].current.byteSize- Size in bytes.
items[].current.contentType- MIME type.
items[].current.createdAt- Added.
items[].current.createdBy- Their ID.
items[].current.createdByKind- Who added it.One of
person,api_key,agent,system items[].current.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].current.durationMs- Videos and audio files: duration.
items[].current.error- Why processing failed.
items[].current.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].current.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].current.folderId- Folder; null for the library root.
items[].current.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.height- Pixels, once processed.
items[].current.id- ID.
items[].current.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].current.name- Name.
items[].current.pageCount- Documents: pages, once processed.
items[].current.processedAt- Processed.
items[].current.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].current.sourceUrl- Where an import came from.
items[].current.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].current.updatedAt- Last change.
items[].current.version- Increments on every change; send as
expectedVersion. items[].current.warnings- Provider-spec findings that don't block use.
items[].current.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].current.warnings[].message- Finding.
items[].current.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].current.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].current.width- Pixels, once processed.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].id- Media.
items[].launches- With
used_in_unpublished_launch: the launches not published yet that use the media. items[].launches[].id- Launch.
items[].launches[].name- Name.
items[].media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAt- Archived; still counted toward media storage until deleted.
items[].media.byteSize- Size in bytes.
items[].media.contentType- MIME type.
items[].media.createdAt- Added.
items[].media.createdBy- Their ID.
items[].media.createdByKind- Who added it.One of
person,api_key,agent,system items[].media.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].media.durationMs- Videos and audio files: duration.
items[].media.error- Why processing failed.
items[].media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].media.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].media.folderId- Folder; null for the library root.
items[].media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.height- Pixels, once processed.
items[].media.id- ID.
items[].media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].media.name- Name.
items[].media.pageCount- Documents: pages, once processed.
items[].media.processedAt- Processed.
items[].media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].media.sourceUrl- Where an import came from.
items[].media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].media.updatedAt- Last change.
items[].media.version- Increments on every change; send as
expectedVersion. items[].media.warnings- Provider-spec findings that don't block use.
items[].media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].media.warnings[].message- Finding.
items[].media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].media.width- Pixels, once processed.
items[].reason- On a rejection an app can act on:
used_in_unpublished_launch(delete). items[].status- Outcome of this item.One of
accepted,rejected,conflict
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f8cc6e5f-0765-4eef-af3b-eae25966f4fc" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"expectedVersion": 3,
"id": "5759e82a-759b-4fb8-bfdc-8170258b64dd"
}
]
}'Start a bulk upload
A folder for many files (folderName finds it by name or makes it) and the ways to fill it: uploader (install, a one-time login that stores an API key in the OS keychain, and the command that uploads a local folder: hashing, skipping files already in the library, parallel parts straight to storage, resuming when run again), uploadLink (the folder's page in the app, where a signed-in member drops files) and import (URL import). media counts the folder's files by status, so asking again shows the progress.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
folderId- An existing folder.
folderName- A folder by name: the existing one (any case), else a new one.
Response
folderid,nameandcreated(made by this request); null for the library root.import- How to import files that are already online.
mediamedia.failed- Failed.
media.processing- Processing.
media.ready- Ready.
media.total- Files.
media.uploading- Uploading.
uploadLink- The folder's page in the app.
uploaderuploader.command- Uploads a local folder; replace
<path>. uploader.install- Saves the uploader (Node 18 or later).
uploader.login- Stores an API key in the OS keychain; a person runs it once.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/bulk-uploads" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3dd7fe26-99fe-41c9-9130-84f2c2aa82cd" \
-H "Content-Type: application/json" \
-d '{
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"folderName": "UGC"
}'Delete media
Deletes for good: the files are removed and stop counting toward media storage. An outcome per item; an item is rejected while uploading or processing, or while a launch that isn't published uses it. Can't be undone.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- 1 to 1000 distinct media.
items[].expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
items[].id- Media.
Response
changesetId- The change record; null when nothing changed.
items- One outcome per item:
mediawhen accepted,errors(andreason,launches) when rejected,currenton a version conflict. items[].current- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAt- Archived; still counted toward media storage until deleted.
items[].current.byteSize- Size in bytes.
items[].current.contentType- MIME type.
items[].current.createdAt- Added.
items[].current.createdBy- Their ID.
items[].current.createdByKind- Who added it.One of
person,api_key,agent,system items[].current.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].current.durationMs- Videos and audio files: duration.
items[].current.error- Why processing failed.
items[].current.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].current.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].current.folderId- Folder; null for the library root.
items[].current.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.height- Pixels, once processed.
items[].current.id- ID.
items[].current.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].current.name- Name.
items[].current.pageCount- Documents: pages, once processed.
items[].current.processedAt- Processed.
items[].current.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].current.sourceUrl- Where an import came from.
items[].current.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].current.updatedAt- Last change.
items[].current.version- Increments on every change; send as
expectedVersion. items[].current.warnings- Provider-spec findings that don't block use.
items[].current.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].current.warnings[].message- Finding.
items[].current.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].current.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].current.width- Pixels, once processed.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].id- Media.
items[].launches- With
used_in_unpublished_launch: the launches not published yet that use the media. items[].launches[].id- Launch.
items[].launches[].name- Name.
items[].media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAt- Archived; still counted toward media storage until deleted.
items[].media.byteSize- Size in bytes.
items[].media.contentType- MIME type.
items[].media.createdAt- Added.
items[].media.createdBy- Their ID.
items[].media.createdByKind- Who added it.One of
person,api_key,agent,system items[].media.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].media.durationMs- Videos and audio files: duration.
items[].media.error- Why processing failed.
items[].media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].media.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].media.folderId- Folder; null for the library root.
items[].media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.height- Pixels, once processed.
items[].media.id- ID.
items[].media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].media.name- Name.
items[].media.pageCount- Documents: pages, once processed.
items[].media.processedAt- Processed.
items[].media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].media.sourceUrl- Where an import came from.
items[].media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].media.updatedAt- Last change.
items[].media.version- Increments on every change; send as
expectedVersion. items[].media.warnings- Provider-spec findings that don't block use.
items[].media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].media.warnings[].message- Finding.
items[].media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].media.width- Pixels, once processed.
items[].reason- On a rejection an app can act on:
used_in_unpublished_launch(delete). items[].status- Outcome of this item.One of
accepted,rejected,conflict
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 13a7f2b4-d9bd-4abe-9b4a-f27413a7d6bb" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"expectedVersion": 3,
"id": "5759e82a-759b-4fb8-bfdc-8170258b64dd"
}
]
}'Import files from URLs
Server-side download over HTTPS of up to 1,000 URLs per job; private and link-local addresses are refused. Returns a job whose items are keyed by position; a few download at once per workspace.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- Files.
items[].folderId- Folder.
items[].name- File name.
items[].url- HTTPS URL.
Response
items- One job item per URL.
items[].key- Job item key.
items[].url- URL.
jobId- The import job; each item's
outputis{mediaId, deduplicated, status}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/imports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c8c4fd9f-2ab8-4a12-ac28-39e11bffaabc" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"name": "Vitamin C Serum",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
}'Get several media items
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ids | string | Optional | Comma-separated media IDs (up to 200); unknown IDs are absent. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- The media found, in the order asked.
items[].archivedAt- Archived; still counted toward media storage until deleted.
items[].byteSize- Size in bytes.
items[].contentType- MIME type.
items[].createdAt- Added.
items[].createdBy- Their ID.
items[].createdByKind- Who added it.One of
person,api_key,agent,system items[].deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].durationMs- Videos and audio files: duration.
items[].error- Why processing failed.
items[].errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].errorParams- The values
errorCode's sentence names, present exactly when it is. items[].folderId- Folder; null for the library root.
items[].hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].height- Pixels, once processed.
items[].id- ID.
items[].kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].name- Name.
items[].pageCount- Documents: pages, once processed.
items[].processedAt- Processed.
items[].sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].sourceUrl- Where an import came from.
items[].status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].updatedAt- Last change.
items[].version- Increments on every change; send as
expectedVersion. items[].warnings- Provider-spec findings that don't block use.
items[].warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].warnings[].message- Finding.
items[].warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].width- Pixels, once processed.
items[].urls- Present once uploaded.
items[].urls.download- The original, saved under the media's name.
items[].urls.expiresAt- When these URLs stop working;
GET /media/{id}/previewnever does. items[].urls.original- Inline view of the original.
items[].urls.preview- A ≤640px JPEG: an image's thumbnail or a video's poster frame.
curl "$PLUTO_API/media/lookup" \
-H "Authorization: Bearer $PLUTO_KEY"Move media to a folder
One command with a changeset; an outcome per item. A stale expectedVersion is that item's conflict, with current.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
folderId- Destination; null for the library root.
items- 1 to 1000 distinct media.
items[].expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
items[].id- Media.
Response
changesetId- The change record; null when nothing changed.
items- One outcome per item:
mediawhen accepted,errors(andreason,launches) when rejected,currenton a version conflict. items[].current- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAt- Archived; still counted toward media storage until deleted.
items[].current.byteSize- Size in bytes.
items[].current.contentType- MIME type.
items[].current.createdAt- Added.
items[].current.createdBy- Their ID.
items[].current.createdByKind- Who added it.One of
person,api_key,agent,system items[].current.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].current.durationMs- Videos and audio files: duration.
items[].current.error- Why processing failed.
items[].current.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].current.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].current.folderId- Folder; null for the library root.
items[].current.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.height- Pixels, once processed.
items[].current.id- ID.
items[].current.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].current.name- Name.
items[].current.pageCount- Documents: pages, once processed.
items[].current.processedAt- Processed.
items[].current.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].current.sourceUrl- Where an import came from.
items[].current.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].current.updatedAt- Last change.
items[].current.version- Increments on every change; send as
expectedVersion. items[].current.warnings- Provider-spec findings that don't block use.
items[].current.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].current.warnings[].message- Finding.
items[].current.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].current.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].current.width- Pixels, once processed.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].id- Media.
items[].launches- With
used_in_unpublished_launch: the launches not published yet that use the media. items[].launches[].id- Launch.
items[].launches[].name- Name.
items[].media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAt- Archived; still counted toward media storage until deleted.
items[].media.byteSize- Size in bytes.
items[].media.contentType- MIME type.
items[].media.createdAt- Added.
items[].media.createdBy- Their ID.
items[].media.createdByKind- Who added it.One of
person,api_key,agent,system items[].media.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].media.durationMs- Videos and audio files: duration.
items[].media.error- Why processing failed.
items[].media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].media.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].media.folderId- Folder; null for the library root.
items[].media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.height- Pixels, once processed.
items[].media.id- ID.
items[].media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].media.name- Name.
items[].media.pageCount- Documents: pages, once processed.
items[].media.processedAt- Processed.
items[].media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].media.sourceUrl- Where an import came from.
items[].media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].media.updatedAt- Last change.
items[].media.version- Increments on every change; send as
expectedVersion. items[].media.warnings- Provider-spec findings that don't block use.
items[].media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].media.warnings[].message- Finding.
items[].media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].media.width- Pixels, once processed.
items[].reason- On a rejection an app can act on:
used_in_unpublished_launch(delete). items[].status- Outcome of this item.One of
accepted,rejected,conflict
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 078e381f-1246-4836-b0ec-673cbec30c9b" \
-H "Content-Type: application/json" \
-d '{
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"items": [
{
"expectedVersion": 3,
"id": "5759e82a-759b-4fb8-bfdc-8170258b64dd"
}
]
}'Unarchive media
Brings archived media back into the library in one command with a changeset; an outcome per item. Each item returns to its folder, and the launches that use it are unchanged. Media that isn't archived is accepted as it is; an item is rejected when it was deleted, or when the same file is already in the library as another item.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- 1 to 1000 distinct media.
items[].expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
items[].id- Media.
Response
changesetId- The change record; null when nothing changed.
items- One outcome per item:
mediawhen accepted,errors(andreason,launches) when rejected,currenton a version conflict. items[].current- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAt- Archived; still counted toward media storage until deleted.
items[].current.byteSize- Size in bytes.
items[].current.contentType- MIME type.
items[].current.createdAt- Added.
items[].current.createdBy- Their ID.
items[].current.createdByKind- Who added it.One of
person,api_key,agent,system items[].current.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].current.durationMs- Videos and audio files: duration.
items[].current.error- Why processing failed.
items[].current.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].current.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].current.folderId- Folder; null for the library root.
items[].current.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.height- Pixels, once processed.
items[].current.id- ID.
items[].current.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].current.name- Name.
items[].current.pageCount- Documents: pages, once processed.
items[].current.processedAt- Processed.
items[].current.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].current.sourceUrl- Where an import came from.
items[].current.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].current.updatedAt- Last change.
items[].current.version- Increments on every change; send as
expectedVersion. items[].current.warnings- Provider-spec findings that don't block use.
items[].current.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].current.warnings[].message- Finding.
items[].current.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].current.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].current.width- Pixels, once processed.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].id- Media.
items[].launches- With
used_in_unpublished_launch: the launches not published yet that use the media. items[].launches[].id- Launch.
items[].launches[].name- Name.
items[].media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAt- Archived; still counted toward media storage until deleted.
items[].media.byteSize- Size in bytes.
items[].media.contentType- MIME type.
items[].media.createdAt- Added.
items[].media.createdBy- Their ID.
items[].media.createdByKind- Who added it.One of
person,api_key,agent,system items[].media.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].media.durationMs- Videos and audio files: duration.
items[].media.error- Why processing failed.
items[].media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].media.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].media.folderId- Folder; null for the library root.
items[].media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.height- Pixels, once processed.
items[].media.id- ID.
items[].media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].media.name- Name.
items[].media.pageCount- Documents: pages, once processed.
items[].media.processedAt- Processed.
items[].media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].media.sourceUrl- Where an import came from.
items[].media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].media.updatedAt- Last change.
items[].media.version- Increments on every change; send as
expectedVersion. items[].media.warnings- Provider-spec findings that don't block use.
items[].media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).items[].media.warnings[].message- Finding.
items[].media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. items[].media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].media.width- Pixels, once processed.
items[].reason- On a rejection an app can act on:
used_in_unpublished_launch(delete). items[].status- Outcome of this item.One of
accepted,rejected,conflict
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/unarchive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2ac6f0aa-eb40-457f-a5ac-e90e53d13b89" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"expectedVersion": 3,
"id": "5759e82a-759b-4fb8-bfdc-8170258b64dd"
}
]
}'Download the bulk uploader
The bulk uploader, a Node script (18 or later, no dependencies): node plutoads-upload.mjs login stores an API key in the OS keychain (macOS Keychain or the Secret Service on Linux) from a hidden prompt, and node plutoads-upload.mjs <path> --folder <id> uploads every image, video and PDF under <path>: SHA-256 per file, files already in the library skipped, 8 MiB parts in parallel straight to storage, the files finished in batches of up to 1,000, and an interrupted run resumed by running it again. It prints a short summary (--json for the counts and failures as JSON).
Response
JavaScript (text/javascript).
Errors
- 400The request is malformed.
curl "$PLUTO_API/media/uploader.mjs"Start an upload
Returns presigned multipart part URLs, or the existing media when the content is already in the library. A new file must fit the organization's media storage: 402 plan_limit (feature media_storage) otherwise.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
byteSize- Size in bytes.
contentType- MIME type.
folderId- Folder.
name- File name.
sha256- Hex SHA-256 of the content; identical content is one media item.
Response
deduplicated- The content is already in the library:
mediais that item and nothing needs uploading. media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAt- Archived; still counted toward media storage until deleted.
media.byteSize- Size in bytes.
media.contentType- MIME type.
media.createdAt- Added.
media.createdBy- Their ID.
media.createdByKind- Who added it.One of
person,api_key,agent,system media.deletedAt- Deleted by a person: the files are gone and no longer counted.
media.durationMs- Videos and audio files: duration.
media.error- Why processing failed.
media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. media.errorParams- The values
errorCode's sentence names, present exactly when it is. media.folderId- Folder; null for the library root.
media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
media.height- Pixels, once processed.
media.id- ID.
media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio media.name- Name.
media.pageCount- Documents: pages, once processed.
media.processedAt- Processed.
media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. media.sourceUrl- Where an import came from.
media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed media.updatedAt- Last change.
media.version- Increments on every change; send as
expectedVersion. media.warnings- Provider-spec findings that don't block use.
media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).media.warnings[].message- Finding.
media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. media.width- Pixels, once processed.
resumed- The content is mid-upload:
uploadhas fresh URLs for it. upload- Where to PUT the bytes:
mode(singleormultipart),method,partSize,headers,parts[](partNumber,byteSize,url),expiresAtand, for a resumed multipart upload,storedParts(the part numbers storage already holds); null when nothing needs uploading.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/uploads" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c001ff58-52d8-4837-8c4b-d4954b64a885" \
-H "Content-Type: application/json" \
-d '{
"byteSize": 18432000,
"contentType": "video/mp4",
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"name": "vitamin-c-serum-ugc-9x16.mp4",
"sha256": "17ab7d1025138f276264e342db16a58112fe4f0e91c6f895fd98ba2951252c5e"
}'Start many uploads
Up to 1,000 files, a few at a time on the server, each its own command. A file still uploading (the same content asked again under a new command) resumes with fresh URLs, and a multipart one lists the parts storage already holds in upload.storedParts. ?view=compact answers without the media: per file index, status (upload, multipart, exists, rejected, conflict), mediaId, then url and the file's own headers (single PUT) or partSize, partCount and parts[] (n, url) of the parts still missing; the headers every single PUT sends are given once at the top, with expiresAt.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
view | string | Optional | full (default) or compact. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- Uploads, each with its own
commandId; 1 to 1,000. items[].byteSize- Size in bytes.
items[].commandId- This item's command ID (1 to 200 characters): a retry with the same ID replays its outcome. Defaults to
<Idempotency-Key>:<index>. items[].contentType- MIME type.
items[].folderId- Folder.
items[].name- File name.
items[].sha256- Hex SHA-256 of the content; identical content is one media item.
Response
items- One outcome per item, in order;
resultwhen accepted. items[].commandId- The item's command ID.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].index- Position in the request.
items[].message- Why it conflicts.
items[].problem- When rejected for a reason other than its fields: the problem the single endpoint answers (
code,status,titleand its details), e.g.plan_limitwhen the file doesn't fit the organization's media storage. The other items still get their own outcome. items[].resultitems[].result.deduplicated- The content is already in the library:
mediais that item and nothing needs uploading. items[].result.media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].result.media.archivedAt- Archived; still counted toward media storage until deleted.
items[].result.media.byteSize- Size in bytes.
items[].result.media.contentType- MIME type.
items[].result.media.createdAt- Added.
items[].result.media.createdBy- Their ID.
items[].result.media.createdByKind- Who added it.One of
person,api_key,agent,system items[].result.media.deletedAt- Deleted by a person: the files are gone and no longer counted.
items[].result.media.durationMs- Videos and audio files: duration.
items[].result.media.error- Why processing failed.
items[].result.media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. items[].result.media.errorParams- The values
errorCode's sentence names, present exactly when it is. items[].result.media.folderId- Folder; null for the library root.
items[].result.media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
items[].result.media.height- Pixels, once processed.
items[].result.media.id- ID.
items[].result.media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio items[].result.media.name- Name.
items[].result.media.pageCount- Documents: pages, once processed.
items[].result.media.processedAt- Processed.
items[].result.media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].result.media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. items[].result.media.sourceUrl- Where an import came from.
items[].result.media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed items[].result.media.updatedAt- Last change.
items[].result.media.version- Increments on every change; send as
expectedVersion. items[].result.media.warnings- Provider-spec findings that don't block use.
items[].result.media.width- Pixels, once processed.
items[].result.resumed- The content is mid-upload:
uploadhas fresh URLs for it. items[].result.upload- Where to PUT the bytes:
mode(singleormultipart),method,partSize,headers,parts[](partNumber,byteSize,url),expiresAtand, for a resumed multipart upload,storedParts(the part numbers storage already holds); null when nothing needs uploading. items[].status- Outcome of this item.One of
accepted,rejected,conflict
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/uploads/batch" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 959b9c63-556a-4106-bfdb-759379c553f3" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"byteSize": 18432000,
"commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
"contentType": "video/mp4",
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"name": "Vitamin C Serum",
"sha256": "7d5a6be7afbe8bffd96c9a4d607e96b0cf2de3c3685f8ded304d31cd392f9e75"
}
]
}'Finish many uploads
Finishes up to 1,000 uploads and queues their processing, each its own command (the one POST /media/{id}/complete claims, so a retry replays the files already finished). A multipart file without parts is completed from the parts storage holds when every one is there; otherwise the item is rejected and names the missing parts. Only infrastructure failures fail the request.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
items- 1 to 1,000 uploads, each media once.
items[].commandId- This item's command ID (1 to 200 characters). Defaults to
<Idempotency-Key>:<index>. items[].mediaId- The media from
POST /media/uploadsor/media/uploads/batch. items[].parts- Multipart only, optional: every part's ETag.
Response
completed- Files finished; processing is queued.
conflicts- Files with no upload to finish.
items- One per item, in order.
items[].commandId- The item's command ID.
items[].errors- Rejected: what to fix.
items[].index- Position in the request.
items[].jobId- Accepted: the processing job.
items[].mediaId- Media.
items[].mediaStatus- Accepted: the media's status now.
items[].message- Why it was refused or conflicts.
items[].status- Outcome of this item.One of
accepted,rejected,conflict rejected- Files refused (missing parts, other bytes than declared).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/uploads/complete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 95f7f987-1a27-4dcd-82f0-8d4bacfad3b3" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"parts": [
{}
]
}
]
}'Get a media item
One media item with short-lived read URLs and the launches that use it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- Archived; still counted toward media storage until deleted.
byteSize- Size in bytes.
contentType- MIME type.
createdAt- Added.
createdBy- Their ID.
createdByKind- Who added it.One of
person,api_key,agent,system deletedAt- Deleted by a person: the files are gone and no longer counted.
durationMs- Videos and audio files: duration.
error- Why processing failed.
errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. errorParams- The values
errorCode's sentence names, present exactly when it is. folderId- Folder; null for the library root.
hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
height- Pixels, once processed.
id- ID.
kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio name- Name.
pageCount- Documents: pages, once processed.
processedAt- Processed.
sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. sourceUrl- Where an import came from.
status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed updatedAt- Last change.
version- Increments on every change; send as
expectedVersion. warnings- Provider-spec findings that don't block use.
warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).warnings[].message- Finding.
warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. width- Pixels, once processed.
launchCount- Launches whose ads use it.
urls- Present once the file is uploaded.
urls.download- The original, saved under the media's name.
urls.expiresAt- When these URLs stop working;
GET /media/{id}/previewnever does. urls.original- Inline view of the original.
urls.preview- A ≤640px JPEG: an image's thumbnail or a video's poster frame.
usage- Launches using it, most recently updated first.
usage[].adCount- Its ads using the media.
usage[].launchId- Launch.
usage[].launchName- Name.
usage[].launchStatus- Status.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701" \
-H "Authorization: Bearer $PLUTO_KEY"Rename or move a media item
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
folderIdname- Name.
Response
archivedAt- Archived; still counted toward media storage until deleted.
byteSize- Size in bytes.
contentType- MIME type.
createdAt- Added.
createdBy- Their ID.
createdByKind- Who added it.One of
person,api_key,agent,system deletedAt- Deleted by a person: the files are gone and no longer counted.
durationMs- Videos and audio files: duration.
error- Why processing failed.
errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. errorParams- The values
errorCode's sentence names, present exactly when it is. folderId- Folder; null for the library root.
hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
height- Pixels, once processed.
id- ID.
kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio name- Name.
pageCount- Documents: pages, once processed.
processedAt- Processed.
sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. sourceUrl- Where an import came from.
status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed updatedAt- Last change.
version- Increments on every change; send as
expectedVersion. warnings- Provider-spec findings that don't block use.
warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).warnings[].message- Finding.
warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. width- Pixels, once processed.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a09a94ca-821b-4529-a8af-42c088b1e90f" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"folderId": "ab9477f7-881a-493c-a181-28d841376527",
"name": "vitamin-c-serum-ugc-9x16.mp4"
}'Delete a media item
Deletes for good: the files are removed and stop counting toward media storage. 409 while it's uploading or processing, or while a launch that isn't published uses it (reason: used_in_unpublished_launch, launches). Deleting deleted media answers with it again.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
expectedVersion | string | Optional | Version. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- Archived; still counted toward media storage until deleted.
byteSize- Size in bytes.
contentType- MIME type.
createdAt- Added.
createdBy- Their ID.
createdByKind- Who added it.One of
person,api_key,agent,system deletedAt- Deleted by a person: the files are gone and no longer counted.
durationMs- Videos and audio files: duration.
error- Why processing failed.
errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. errorParams- The values
errorCode's sentence names, present exactly when it is. folderId- Folder; null for the library root.
hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
height- Pixels, once processed.
id- ID.
kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio name- Name.
pageCount- Documents: pages, once processed.
processedAt- Processed.
sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. sourceUrl- Where an import came from.
status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed updatedAt- Last change.
version- Increments on every change; send as
expectedVersion. warnings- Provider-spec findings that don't block use.
warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).warnings[].message- Finding.
warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. width- Pixels, once processed.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Uploading, processing, or used by a launch that isn't published.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1647a08c-e4e8-4bf3-8a56-794f8de9ba42"Cancel an upload
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- Archived; still counted toward media storage until deleted.
byteSize- Size in bytes.
contentType- MIME type.
createdAt- Added.
createdBy- Their ID.
createdByKind- Who added it.One of
person,api_key,agent,system deletedAt- Deleted by a person: the files are gone and no longer counted.
durationMs- Videos and audio files: duration.
error- Why processing failed.
errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. errorParams- The values
errorCode's sentence names, present exactly when it is. folderId- Folder; null for the library root.
hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
height- Pixels, once processed.
id- ID.
kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio name- Name.
pageCount- Documents: pages, once processed.
processedAt- Processed.
sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. sourceUrl- Where an import came from.
status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed updatedAt- Last change.
version- Increments on every change; send as
expectedVersion. warnings- Provider-spec findings that don't block use.
warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).warnings[].message- Finding.
warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. width- Pixels, once processed.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/abort" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7fbdca1d-1921-4e3d-8003-2acee5adfddf"Archive a media item
The body is optional. Ads already using it keep working.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
Response
archivedAt- Archived; still counted toward media storage until deleted.
byteSize- Size in bytes.
contentType- MIME type.
createdAt- Added.
createdBy- Their ID.
createdByKind- Who added it.One of
person,api_key,agent,system deletedAt- Deleted by a person: the files are gone and no longer counted.
durationMs- Videos and audio files: duration.
error- Why processing failed.
errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. errorParams- The values
errorCode's sentence names, present exactly when it is. folderId- Folder; null for the library root.
hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
height- Pixels, once processed.
id- ID.
kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio name- Name.
pageCount- Documents: pages, once processed.
processedAt- Processed.
sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. sourceUrl- Where an import came from.
status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed updatedAt- Last change.
version- Increments on every change; send as
expectedVersion. warnings- Provider-spec findings that don't block use.
warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).warnings[].message- Finding.
warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. width- Pixels, once processed.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: bf4fa159-b623-4d2c-8637-31f96d663a2f" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Finish an upload and queue processing
A multipart upload may come without parts: it is completed from the parts storage holds when every one is there, and otherwise refused with the missing parts named.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
parts- Uploaded parts; optional for a multipart upload.
Response
jobId- The processing job.
media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAt- Archived; still counted toward media storage until deleted.
media.byteSize- Size in bytes.
media.contentType- MIME type.
media.createdAt- Added.
media.createdBy- Their ID.
media.createdByKind- Who added it.One of
person,api_key,agent,system media.deletedAt- Deleted by a person: the files are gone and no longer counted.
media.durationMs- Videos and audio files: duration.
media.error- Why processing failed.
media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. media.errorParams- The values
errorCode's sentence names, present exactly when it is. media.folderId- Folder; null for the library root.
media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
media.height- Pixels, once processed.
media.id- ID.
media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio media.name- Name.
media.pageCount- Documents: pages, once processed.
media.processedAt- Processed.
media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. media.sourceUrl- Where an import came from.
media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed media.updatedAt- Last change.
media.version- Increments on every change; send as
expectedVersion. media.warnings- Provider-spec findings that don't block use.
media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).media.warnings[].message- Finding.
media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. media.width- Pixels, once processed.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/complete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b1ac69ac-bd81-433b-9b8a-928f0e1aa3f1" \
-H "Content-Type: application/json" \
-d '{
"parts": [
{}
]
}'Get a preview link
Stable link to a preview or original.
A ready item's preview answers the JPEG itself (200, kept privately by the browser for a year with an ETag: a media item's preview never changes). Otherwise (variant=original, a file still processing, no preview) it redirects to a fresh short-lived URL, so saved references keep working.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
variant | string | Optional | preview (default) or original. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/preview" \
-H "Authorization: Bearer $PLUTO_KEY"Get what a model sees of a media item
Stills sized for vision models, as short-lived URLs: an image's still (at most 1568 px), or up to 8 evenly spaced frames of a video (at most 1024 px) with their timestamps, plus its aspect ratio and whether it has sound. Stills are made once and kept; the first view of a video may wait a few seconds while its frames are taken. note says why there's nothing (or less) to look at, e.g. still processing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
aspectRatio- As ad specs name it:
9:16,4:5,1.91:1. expiresAt- When the still URLs stop working.
hasAudio- Videos: whether there is a sound track.
media- An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAt- Archived; still counted toward media storage until deleted.
media.byteSize- Size in bytes.
media.contentType- MIME type.
media.createdAt- Added.
media.createdBy- Their ID.
media.createdByKind- Who added it.One of
person,api_key,agent,system media.deletedAt- Deleted by a person: the files are gone and no longer counted.
media.durationMs- Videos and audio files: duration.
media.error- Why processing failed.
media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. media.errorParams- The values
errorCode's sentence names, present exactly when it is. media.folderId- Folder; null for the library root.
media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
media.height- Pixels, once processed.
media.id- ID.
media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio media.name- Name.
media.pageCount- Documents: pages, once processed.
media.processedAt- Processed.
media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. media.sourceUrl- Where an import came from.
media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed media.updatedAt- Last change.
media.version- Increments on every change; send as
expectedVersion. media.warnings- Provider-spec findings that don't block use.
media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).media.warnings[].message- Finding.
media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. media.width- Pixels, once processed.
note- Why there's nothing (or less) to look at.
stills- In order: one for an image, up to 8 frames for a video.
stills[].at- Videos: the same as a timestamp, e.g.
0:04. stills[].atMs- Videos: where the frame is (ms).
stills[].height- Pixels.
stills[].url- Short-lived URL of the JPEG.
stills[].width- Pixels.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/view" \
-H "Authorization: Bearer $PLUTO_KEY"