API reference

Media

Upload, import, organize and archive images and videos.

GET/media

List the media library

Permission: read

Parameters

NameTypeRequiredDescription
folderIdquerystringOptionalFolder.
kindquerystringOptionalimage, video, document or audio, or several comma-separated; without one, images and videos.
statusquerystringOptionalProcessing status.
qquerystringOptionalSearch.
usagequerystringOptionalused or unused.
archivedquerystringOptionalexclude (default), include or only. Archived media still counts toward media storage until deleted.
sortquerystringOptionalnewest (default), oldest, name, size (largest first), usage (in the most launches first) or least_used.
tagsquerystringOptionalTag (workflow label) IDs, comma-separated, up to 50: only files used by an ad that isn't archived and has any of them.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].byteSizeinteger
Size in bytes.
items[].contentTypestring
MIME type.
items[].createdAtstring (date-time)
Added.
items[].createdBystring (uuid)
Their ID.
items[].createdByKindstring
Who added it.One of person, api_key, agent, system
items[].deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].durationMsinteger or null
Videos and audio files: duration.
items[].errorstring or null
Why processing failed.
items[].errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].folderIdstring (uuid) or null
Folder; null for the library root.
items[].hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].heightinteger or null
Pixels, once processed.
items[].idstring (uuid)Required
ID.
items[].kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].namestring
Name.
items[].pageCountinteger or null
Documents: pages, once processed.
items[].processedAtstring (date-time) or null
Processed.
items[].sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].sourceUrlstring or null
Where an import came from.
items[].statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].updatedAtstring (date-time)
Last change.
items[].versioninteger
Increments on every change; send as expectedVersion.
items[].warningsarray of objects
Provider-spec findings that don't block use.
items[].warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].warnings[].messagestringRequired
Finding.
items[].warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].widthinteger or null
Pixels, once processed.
items[].launchCountintegerRequired
Launches whose ads use it.
items[].previewUrlstring or null
Short-lived thumbnail URL (a video's poster frame).
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/media" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/media/archive

Archive media

One command with a changeset; an outcome per item. Ads already using archived media keep working.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
1 to 1000 distinct media.
items[].expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
items[].idstring (uuid)Required
Media.

Response200 OK

changesetIdstring (uuid) or null
The change record; null when nothing changed.
itemsarray of objectsRequired
One outcome per item: media when accepted, errors (and reason, launches) when rejected, current on a version conflict.
items[].currentobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].current.byteSizeinteger
Size in bytes.
items[].current.contentTypestring
MIME type.
items[].current.createdAtstring (date-time)
Added.
items[].current.createdBystring (uuid)
Their ID.
items[].current.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].current.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].current.durationMsinteger or null
Videos and audio files: duration.
items[].current.errorstring or null
Why processing failed.
items[].current.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].current.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].current.folderIdstring (uuid) or null
Folder; null for the library root.
items[].current.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.heightinteger or null
Pixels, once processed.
items[].current.idstring (uuid)Required
ID.
items[].current.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].current.namestring
Name.
items[].current.pageCountinteger or null
Documents: pages, once processed.
items[].current.processedAtstring (date-time) or null
Processed.
items[].current.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].current.sourceUrlstring or null
Where an import came from.
items[].current.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].current.updatedAtstring (date-time)
Last change.
items[].current.versioninteger
Increments on every change; send as expectedVersion.
items[].current.warningsarray of objects
Provider-spec findings that don't block use.
items[].current.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].current.warnings[].messagestringRequired
Finding.
items[].current.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].current.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].current.widthinteger or null
Pixels, once processed.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].idstring (uuid)Required
Media.
items[].launchesarray of objects
With used_in_unpublished_launch: the launches not published yet that use the media.
items[].launches[].idstring (uuid)Required
Launch.
items[].launches[].namestringRequired
Name.
items[].mediaobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].media.byteSizeinteger
Size in bytes.
items[].media.contentTypestring
MIME type.
items[].media.createdAtstring (date-time)
Added.
items[].media.createdBystring (uuid)
Their ID.
items[].media.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].media.durationMsinteger or null
Videos and audio files: duration.
items[].media.errorstring or null
Why processing failed.
items[].media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].media.folderIdstring (uuid) or null
Folder; null for the library root.
items[].media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.heightinteger or null
Pixels, once processed.
items[].media.idstring (uuid)Required
ID.
items[].media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].media.namestring
Name.
items[].media.pageCountinteger or null
Documents: pages, once processed.
items[].media.processedAtstring (date-time) or null
Processed.
items[].media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].media.sourceUrlstring or null
Where an import came from.
items[].media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].media.updatedAtstring (date-time)
Last change.
items[].media.versioninteger
Increments on every change; send as expectedVersion.
items[].media.warningsarray of objects
Provider-spec findings that don't block use.
items[].media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].media.warnings[].messagestringRequired
Finding.
items[].media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].media.widthinteger or null
Pixels, once processed.
items[].reasonstring
On a rejection an app can act on: used_in_unpublished_launch (delete).
items[].statusstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
      }
    ]
  }'
POST/media/bulk-uploads

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

folderIdstring (uuid)
An existing folder.
folderNamestring
A folder by name: the existing one (any case), else a new one.

Response200 OK

folderobject or nullRequired
id, name and created (made by this request); null for the library root.
importstringRequired
How to import files that are already online.
mediaobjectRequired
media.failedintegerRequired
Failed.
media.processingintegerRequired
Processing.
media.readyintegerRequired
Ready.
media.totalintegerRequired
Files.
media.uploadingintegerRequired
Uploading.
uploadLinkstringRequired
The folder's page in the app.
uploaderobjectRequired
uploader.commandstringRequired
Uploads a local folder; replace <path>.
uploader.installstringRequired
Saves the uploader (Node 18 or later).
uploader.loginstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
POST/media/delete

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
1 to 1000 distinct media.
items[].expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
items[].idstring (uuid)Required
Media.

Response200 OK

changesetIdstring (uuid) or null
The change record; null when nothing changed.
itemsarray of objectsRequired
One outcome per item: media when accepted, errors (and reason, launches) when rejected, current on a version conflict.
items[].currentobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].current.byteSizeinteger
Size in bytes.
items[].current.contentTypestring
MIME type.
items[].current.createdAtstring (date-time)
Added.
items[].current.createdBystring (uuid)
Their ID.
items[].current.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].current.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].current.durationMsinteger or null
Videos and audio files: duration.
items[].current.errorstring or null
Why processing failed.
items[].current.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].current.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].current.folderIdstring (uuid) or null
Folder; null for the library root.
items[].current.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.heightinteger or null
Pixels, once processed.
items[].current.idstring (uuid)Required
ID.
items[].current.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].current.namestring
Name.
items[].current.pageCountinteger or null
Documents: pages, once processed.
items[].current.processedAtstring (date-time) or null
Processed.
items[].current.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].current.sourceUrlstring or null
Where an import came from.
items[].current.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].current.updatedAtstring (date-time)
Last change.
items[].current.versioninteger
Increments on every change; send as expectedVersion.
items[].current.warningsarray of objects
Provider-spec findings that don't block use.
items[].current.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].current.warnings[].messagestringRequired
Finding.
items[].current.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].current.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].current.widthinteger or null
Pixels, once processed.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].idstring (uuid)Required
Media.
items[].launchesarray of objects
With used_in_unpublished_launch: the launches not published yet that use the media.
items[].launches[].idstring (uuid)Required
Launch.
items[].launches[].namestringRequired
Name.
items[].mediaobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].media.byteSizeinteger
Size in bytes.
items[].media.contentTypestring
MIME type.
items[].media.createdAtstring (date-time)
Added.
items[].media.createdBystring (uuid)
Their ID.
items[].media.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].media.durationMsinteger or null
Videos and audio files: duration.
items[].media.errorstring or null
Why processing failed.
items[].media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].media.folderIdstring (uuid) or null
Folder; null for the library root.
items[].media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.heightinteger or null
Pixels, once processed.
items[].media.idstring (uuid)Required
ID.
items[].media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].media.namestring
Name.
items[].media.pageCountinteger or null
Documents: pages, once processed.
items[].media.processedAtstring (date-time) or null
Processed.
items[].media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].media.sourceUrlstring or null
Where an import came from.
items[].media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].media.updatedAtstring (date-time)
Last change.
items[].media.versioninteger
Increments on every change; send as expectedVersion.
items[].media.warningsarray of objects
Provider-spec findings that don't block use.
items[].media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].media.warnings[].messagestringRequired
Finding.
items[].media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].media.widthinteger or null
Pixels, once processed.
items[].reasonstring
On a rejection an app can act on: used_in_unpublished_launch (delete).
items[].statusstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
      }
    ]
  }'
POST/media/imports

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
Files.
items[].folderIdstring (uuid)
Folder.
items[].namestring
File name.
items[].urlstringRequired
HTTPS URL.

Response200 OK

itemsarray of objectsRequired
One job item per URL.
items[].keystringRequired
Job item key.
items[].urlstringRequired
URL.
jobIdstring (uuid)Required
The import job; each item's output is {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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/media/lookup

Get several media items

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idsquerystringOptionalComma-separated media IDs (up to 200); unknown IDs are absent.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
The media found, in the order asked.
items[].archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].byteSizeinteger
Size in bytes.
items[].contentTypestring
MIME type.
items[].createdAtstring (date-time)
Added.
items[].createdBystring (uuid)
Their ID.
items[].createdByKindstring
Who added it.One of person, api_key, agent, system
items[].deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].durationMsinteger or null
Videos and audio files: duration.
items[].errorstring or null
Why processing failed.
items[].errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].folderIdstring (uuid) or null
Folder; null for the library root.
items[].hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].heightinteger or null
Pixels, once processed.
items[].idstring (uuid)Required
ID.
items[].kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].namestring
Name.
items[].pageCountinteger or null
Documents: pages, once processed.
items[].processedAtstring (date-time) or null
Processed.
items[].sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].sourceUrlstring or null
Where an import came from.
items[].statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].updatedAtstring (date-time)
Last change.
items[].versioninteger
Increments on every change; send as expectedVersion.
items[].warningsarray of objects
Provider-spec findings that don't block use.
items[].warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].warnings[].messagestringRequired
Finding.
items[].warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].widthinteger or null
Pixels, once processed.
items[].urlsobject or null
Present once uploaded.
items[].urls.downloadstringRequired
The original, saved under the media's name.
items[].urls.expiresAtstring (date-time)Required
When these URLs stop working; GET /media/{id}/preview never does.
items[].urls.originalstringRequired
Inline view of the original.
items[].urls.previewstring or null
A ≤640px JPEG: an image's thumbnail or a video's poster frame.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/media/lookup" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/media/move

Move media to a folder

One command with a changeset; an outcome per item. A stale expectedVersion is that item's conflict, with current.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

folderIdstring (uuid) or nullRequired
Destination; null for the library root.
itemsarray of objectsRequired
1 to 1000 distinct media.
items[].expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
items[].idstring (uuid)Required
Media.

Response200 OK

changesetIdstring (uuid) or null
The change record; null when nothing changed.
itemsarray of objectsRequired
One outcome per item: media when accepted, errors (and reason, launches) when rejected, current on a version conflict.
items[].currentobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].current.byteSizeinteger
Size in bytes.
items[].current.contentTypestring
MIME type.
items[].current.createdAtstring (date-time)
Added.
items[].current.createdBystring (uuid)
Their ID.
items[].current.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].current.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].current.durationMsinteger or null
Videos and audio files: duration.
items[].current.errorstring or null
Why processing failed.
items[].current.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].current.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].current.folderIdstring (uuid) or null
Folder; null for the library root.
items[].current.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.heightinteger or null
Pixels, once processed.
items[].current.idstring (uuid)Required
ID.
items[].current.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].current.namestring
Name.
items[].current.pageCountinteger or null
Documents: pages, once processed.
items[].current.processedAtstring (date-time) or null
Processed.
items[].current.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].current.sourceUrlstring or null
Where an import came from.
items[].current.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].current.updatedAtstring (date-time)
Last change.
items[].current.versioninteger
Increments on every change; send as expectedVersion.
items[].current.warningsarray of objects
Provider-spec findings that don't block use.
items[].current.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].current.warnings[].messagestringRequired
Finding.
items[].current.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].current.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].current.widthinteger or null
Pixels, once processed.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].idstring (uuid)Required
Media.
items[].launchesarray of objects
With used_in_unpublished_launch: the launches not published yet that use the media.
items[].launches[].idstring (uuid)Required
Launch.
items[].launches[].namestringRequired
Name.
items[].mediaobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].media.byteSizeinteger
Size in bytes.
items[].media.contentTypestring
MIME type.
items[].media.createdAtstring (date-time)
Added.
items[].media.createdBystring (uuid)
Their ID.
items[].media.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].media.durationMsinteger or null
Videos and audio files: duration.
items[].media.errorstring or null
Why processing failed.
items[].media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].media.folderIdstring (uuid) or null
Folder; null for the library root.
items[].media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.heightinteger or null
Pixels, once processed.
items[].media.idstring (uuid)Required
ID.
items[].media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].media.namestring
Name.
items[].media.pageCountinteger or null
Documents: pages, once processed.
items[].media.processedAtstring (date-time) or null
Processed.
items[].media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].media.sourceUrlstring or null
Where an import came from.
items[].media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].media.updatedAtstring (date-time)
Last change.
items[].media.versioninteger
Increments on every change; send as expectedVersion.
items[].media.warningsarray of objects
Provider-spec findings that don't block use.
items[].media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].media.warnings[].messagestringRequired
Finding.
items[].media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].media.widthinteger or null
Pixels, once processed.
items[].reasonstring
On a rejection an app can act on: used_in_unpublished_launch (delete).
items[].statusstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
      }
    ]
  }'
POST/media/unarchive

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
1 to 1000 distinct media.
items[].expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
items[].idstring (uuid)Required
Media.

Response200 OK

changesetIdstring (uuid) or null
The change record; null when nothing changed.
itemsarray of objectsRequired
One outcome per item: media when accepted, errors (and reason, launches) when rejected, current on a version conflict.
items[].currentobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].current.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].current.byteSizeinteger
Size in bytes.
items[].current.contentTypestring
MIME type.
items[].current.createdAtstring (date-time)
Added.
items[].current.createdBystring (uuid)
Their ID.
items[].current.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].current.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].current.durationMsinteger or null
Videos and audio files: duration.
items[].current.errorstring or null
Why processing failed.
items[].current.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].current.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].current.folderIdstring (uuid) or null
Folder; null for the library root.
items[].current.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].current.heightinteger or null
Pixels, once processed.
items[].current.idstring (uuid)Required
ID.
items[].current.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].current.namestring
Name.
items[].current.pageCountinteger or null
Documents: pages, once processed.
items[].current.processedAtstring (date-time) or null
Processed.
items[].current.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].current.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].current.sourceUrlstring or null
Where an import came from.
items[].current.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].current.updatedAtstring (date-time)
Last change.
items[].current.versioninteger
Increments on every change; send as expectedVersion.
items[].current.warningsarray of objects
Provider-spec findings that don't block use.
items[].current.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].current.warnings[].messagestringRequired
Finding.
items[].current.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].current.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].current.widthinteger or null
Pixels, once processed.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].idstring (uuid)Required
Media.
items[].launchesarray of objects
With used_in_unpublished_launch: the launches not published yet that use the media.
items[].launches[].idstring (uuid)Required
Launch.
items[].launches[].namestringRequired
Name.
items[].mediaobject
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].media.byteSizeinteger
Size in bytes.
items[].media.contentTypestring
MIME type.
items[].media.createdAtstring (date-time)
Added.
items[].media.createdBystring (uuid)
Their ID.
items[].media.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].media.durationMsinteger or null
Videos and audio files: duration.
items[].media.errorstring or null
Why processing failed.
items[].media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].media.folderIdstring (uuid) or null
Folder; null for the library root.
items[].media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].media.heightinteger or null
Pixels, once processed.
items[].media.idstring (uuid)Required
ID.
items[].media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].media.namestring
Name.
items[].media.pageCountinteger or null
Documents: pages, once processed.
items[].media.processedAtstring (date-time) or null
Processed.
items[].media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].media.sourceUrlstring or null
Where an import came from.
items[].media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].media.updatedAtstring (date-time)
Last change.
items[].media.versioninteger
Increments on every change; send as expectedVersion.
items[].media.warningsarray of objects
Provider-spec findings that don't block use.
items[].media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
items[].media.warnings[].messagestringRequired
Finding.
items[].media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
items[].media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].media.widthinteger or null
Pixels, once processed.
items[].reasonstring
On a rejection an app can act on: used_in_unpublished_launch (delete).
items[].statusstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
      }
    ]
  }'
GET/media/uploader.mjs

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).

No credential

Response200 OK

JavaScript (text/javascript).

Errors

  • 400The request is malformed.
curl "$PLUTO_API/media/uploader.mjs"
POST/media/uploads

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

byteSizeintegerRequired
Size in bytes.
contentTypestringRequired
MIME type.
folderIdstring (uuid)
Folder.
namestringRequired
File name.
sha256stringRequired
Hex SHA-256 of the content; identical content is one media item.

Response200 OK

deduplicatedbooleanRequired
The content is already in the library: media is that item and nothing needs uploading.
mediaobjectRequired
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
media.byteSizeinteger
Size in bytes.
media.contentTypestring
MIME type.
media.createdAtstring (date-time)
Added.
media.createdBystring (uuid)
Their ID.
media.createdByKindstring
Who added it.One of person, api_key, agent, system
media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
media.durationMsinteger or null
Videos and audio files: duration.
media.errorstring or null
Why processing failed.
media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
media.folderIdstring (uuid) or null
Folder; null for the library root.
media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
media.heightinteger or null
Pixels, once processed.
media.idstring (uuid)Required
ID.
media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
media.namestring
Name.
media.pageCountinteger or null
Documents: pages, once processed.
media.processedAtstring (date-time) or null
Processed.
media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
media.sourceUrlstring or null
Where an import came from.
media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
media.updatedAtstring (date-time)
Last change.
media.versioninteger
Increments on every change; send as expectedVersion.
media.warningsarray of objects
Provider-spec findings that don't block use.
media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
media.warnings[].messagestringRequired
Finding.
media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
media.widthinteger or null
Pixels, once processed.
resumedbooleanRequired
The content is mid-upload: upload has fresh URLs for it.
uploadobject or null
Where to PUT the bytes: mode (single or multipart), method, partSize, headers, parts[] (partNumber, byteSize, url), expiresAt and, 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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
POST/media/uploads/batch

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
viewquerystringOptionalfull (default) or compact.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
Uploads, each with its own commandId; 1 to 1,000.
items[].byteSizeintegerRequired
Size in bytes.
items[].commandIdstring
This item's command ID (1 to 200 characters): a retry with the same ID replays its outcome. Defaults to <Idempotency-Key>:<index>.
items[].contentTypestringRequired
MIME type.
items[].folderIdstring (uuid)
Folder.
items[].namestringRequired
File name.
items[].sha256stringRequired
Hex SHA-256 of the content; identical content is one media item.

Response200 OK

itemsarray of objectsRequired
One outcome per item, in order; result when accepted.
items[].commandIdstringRequired
The item's command ID.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].indexintegerRequired
Position in the request.
items[].messagestring
Why it conflicts.
items[].problemobject
When rejected for a reason other than its fields: the problem the single endpoint answers (code, status, title and its details), e.g. plan_limit when the file doesn't fit the organization's media storage. The other items still get their own outcome.
items[].resultobject
items[].result.deduplicatedbooleanRequired
The content is already in the library: media is that item and nothing needs uploading.
items[].result.mediaobjectRequired
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
items[].result.media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
items[].result.media.byteSizeinteger
Size in bytes.
items[].result.media.contentTypestring
MIME type.
items[].result.media.createdAtstring (date-time)
Added.
items[].result.media.createdBystring (uuid)
Their ID.
items[].result.media.createdByKindstring
Who added it.One of person, api_key, agent, system
items[].result.media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
items[].result.media.durationMsinteger or null
Videos and audio files: duration.
items[].result.media.errorstring or null
Why processing failed.
items[].result.media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
items[].result.media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
items[].result.media.folderIdstring (uuid) or null
Folder; null for the library root.
items[].result.media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
items[].result.media.heightinteger or null
Pixels, once processed.
items[].result.media.idstring (uuid)Required
ID.
items[].result.media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
items[].result.media.namestring
Name.
items[].result.media.pageCountinteger or null
Documents: pages, once processed.
items[].result.media.processedAtstring (date-time) or null
Processed.
items[].result.media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
items[].result.media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
items[].result.media.sourceUrlstring or null
Where an import came from.
items[].result.media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
items[].result.media.updatedAtstring (date-time)
Last change.
items[].result.media.versioninteger
Increments on every change; send as expectedVersion.
items[].result.media.warningsarray of objects
Provider-spec findings that don't block use.
items[].result.media.widthinteger or null
Pixels, once processed.
items[].result.resumedbooleanRequired
The content is mid-upload: upload has fresh URLs for it.
items[].result.uploadobject or null
Where to PUT the bytes: mode (single or multipart), method, partSize, headers, parts[] (partNumber, byteSize, url), expiresAt and, for a resumed multipart upload, storedParts (the part numbers storage already holds); null when nothing needs uploading.
items[].statusstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
      }
    ]
  }'
POST/media/uploads/complete

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

itemsarray of objectsRequired
1 to 1,000 uploads, each media once.
items[].commandIdstring
This item's command ID (1 to 200 characters). Defaults to <Idempotency-Key>:<index>.
items[].mediaIdstring (uuid)Required
The media from POST /media/uploads or /media/uploads/batch.
items[].partsarray of objects
Multipart only, optional: every part's ETag.

Response200 OK

completedintegerRequired
Files finished; processing is queued.
conflictsintegerRequired
Files with no upload to finish.
itemsarray of objectsRequired
One per item, in order.
items[].commandIdstringRequired
The item's command ID.
items[].errorsarray of objects
Rejected: what to fix.
items[].indexintegerRequired
Position in the request.
items[].jobIdstring (uuid)
Accepted: the processing job.
items[].mediaIdstring (uuid)Required
Media.
items[].mediaStatusstring
Accepted: the media's status now.
items[].messagestring
Why it was refused or conflicts.
items[].statusstringRequired
Outcome of this item.One of accepted, rejected, conflict
rejectedintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/media/{id}

Get a media item

One media item with short-lived read URLs and the launches that use it.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
byteSizeinteger
Size in bytes.
contentTypestring
MIME type.
createdAtstring (date-time)
Added.
createdBystring (uuid)
Their ID.
createdByKindstring
Who added it.One of person, api_key, agent, system
deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
durationMsinteger or null
Videos and audio files: duration.
errorstring or null
Why processing failed.
errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
errorParamsobject
The values errorCode's sentence names, present exactly when it is.
folderIdstring (uuid) or null
Folder; null for the library root.
hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
heightinteger or null
Pixels, once processed.
idstring (uuid)Required
ID.
kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
namestring
Name.
pageCountinteger or null
Documents: pages, once processed.
processedAtstring (date-time) or null
Processed.
sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
sourceUrlstring or null
Where an import came from.
statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.
warningsarray of objects
Provider-spec findings that don't block use.
warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
warnings[].messagestringRequired
Finding.
warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
widthinteger or null
Pixels, once processed.
launchCountintegerRequired
Launches whose ads use it.
urlsobject or null
Present once the file is uploaded.
urls.downloadstringRequired
The original, saved under the media's name.
urls.expiresAtstring (date-time)Required
When these URLs stop working; GET /media/{id}/preview never does.
urls.originalstringRequired
Inline view of the original.
urls.previewstring or null
A ≤640px JPEG: an image's thumbnail or a video's poster frame.
usagearray of objectsRequired
Launches using it, most recently updated first.
usage[].adCountintegerRequired
Its ads using the media.
usage[].launchIdstring (uuid)Required
Launch.
usage[].launchNamestringRequired
Name.
usage[].launchStatusstringRequired
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-After seconds. 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"
PATCH/media/{id}

Rename or move a media item

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
folderIdstring (uuid) or null
namestring
Name.

Response200 OK

archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
byteSizeinteger
Size in bytes.
contentTypestring
MIME type.
createdAtstring (date-time)
Added.
createdBystring (uuid)
Their ID.
createdByKindstring
Who added it.One of person, api_key, agent, system
deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
durationMsinteger or null
Videos and audio files: duration.
errorstring or null
Why processing failed.
errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
errorParamsobject
The values errorCode's sentence names, present exactly when it is.
folderIdstring (uuid) or null
Folder; null for the library root.
hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
heightinteger or null
Pixels, once processed.
idstring (uuid)Required
ID.
kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
namestring
Name.
pageCountinteger or null
Documents: pages, once processed.
processedAtstring (date-time) or null
Processed.
sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
sourceUrlstring or null
Where an import came from.
statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.
warningsarray of objects
Provider-spec findings that don't block use.
warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
warnings[].messagestringRequired
Finding.
warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
widthinteger or null
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/media/{id}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
expectedVersionquerystringOptionalVersion.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
byteSizeinteger
Size in bytes.
contentTypestring
MIME type.
createdAtstring (date-time)
Added.
createdBystring (uuid)
Their ID.
createdByKindstring
Who added it.One of person, api_key, agent, system
deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
durationMsinteger or null
Videos and audio files: duration.
errorstring or null
Why processing failed.
errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
errorParamsobject
The values errorCode's sentence names, present exactly when it is.
folderIdstring (uuid) or null
Folder; null for the library root.
hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
heightinteger or null
Pixels, once processed.
idstring (uuid)Required
ID.
kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
namestring
Name.
pageCountinteger or null
Documents: pages, once processed.
processedAtstring (date-time) or null
Processed.
sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
sourceUrlstring or null
Where an import came from.
statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.
warningsarray of objects
Provider-spec findings that don't block use.
warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
warnings[].messagestringRequired
Finding.
warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
widthinteger or null
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
POST/media/{id}/abort

Cancel an upload

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
byteSizeinteger
Size in bytes.
contentTypestring
MIME type.
createdAtstring (date-time)
Added.
createdBystring (uuid)
Their ID.
createdByKindstring
Who added it.One of person, api_key, agent, system
deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
durationMsinteger or null
Videos and audio files: duration.
errorstring or null
Why processing failed.
errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
errorParamsobject
The values errorCode's sentence names, present exactly when it is.
folderIdstring (uuid) or null
Folder; null for the library root.
hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
heightinteger or null
Pixels, once processed.
idstring (uuid)Required
ID.
kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
namestring
Name.
pageCountinteger or null
Documents: pages, once processed.
processedAtstring (date-time) or null
Processed.
sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
sourceUrlstring or null
Where an import came from.
statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.
warningsarray of objects
Provider-spec findings that don't block use.
warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
warnings[].messagestringRequired
Finding.
warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
widthinteger or null
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
POST/media/{id}/archive

Archive a media item

The body is optional. Ads already using it keep working.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
byteSizeinteger
Size in bytes.
contentTypestring
MIME type.
createdAtstring (date-time)
Added.
createdBystring (uuid)
Their ID.
createdByKindstring
Who added it.One of person, api_key, agent, system
deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
durationMsinteger or null
Videos and audio files: duration.
errorstring or null
Why processing failed.
errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
errorParamsobject
The values errorCode's sentence names, present exactly when it is.
folderIdstring (uuid) or null
Folder; null for the library root.
hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
heightinteger or null
Pixels, once processed.
idstring (uuid)Required
ID.
kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
namestring
Name.
pageCountinteger or null
Documents: pages, once processed.
processedAtstring (date-time) or null
Processed.
sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
sourceUrlstring or null
Where an import came from.
statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.
warningsarray of objects
Provider-spec findings that don't block use.
warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
warnings[].messagestringRequired
Finding.
warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
widthinteger or null
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/media/{id}/complete

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

partsarray of objects
Uploaded parts; optional for a multipart upload.

Response200 OK

jobIdstring (uuid)Required
The processing job.
mediaobjectRequired
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
media.byteSizeinteger
Size in bytes.
media.contentTypestring
MIME type.
media.createdAtstring (date-time)
Added.
media.createdBystring (uuid)
Their ID.
media.createdByKindstring
Who added it.One of person, api_key, agent, system
media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
media.durationMsinteger or null
Videos and audio files: duration.
media.errorstring or null
Why processing failed.
media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
media.folderIdstring (uuid) or null
Folder; null for the library root.
media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
media.heightinteger or null
Pixels, once processed.
media.idstring (uuid)Required
ID.
media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
media.namestring
Name.
media.pageCountinteger or null
Documents: pages, once processed.
media.processedAtstring (date-time) or null
Processed.
media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
media.sourceUrlstring or null
Where an import came from.
media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
media.updatedAtstring (date-time)
Last change.
media.versioninteger
Increments on every change; send as expectedVersion.
media.warningsarray of objects
Provider-spec findings that don't block use.
media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
media.warnings[].messagestringRequired
Finding.
media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
media.widthinteger or null
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/media/{id}/preview

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.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
variantquerystringOptionalpreview (default) or original.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response302 Found

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-After seconds. 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/media/{id}/view

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.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

aspectRatiostring or null
As ad specs name it: 9:16, 4:5, 1.91:1.
expiresAtstring (date-time)Required
When the still URLs stop working.
hasAudioboolean or null
Videos: whether there is a sound track.
mediaobjectRequired
An image, video, document or audio file. Bytes stay in storage; reference media by ID.
media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
media.byteSizeinteger
Size in bytes.
media.contentTypestring
MIME type.
media.createdAtstring (date-time)
Added.
media.createdBystring (uuid)
Their ID.
media.createdByKindstring
Who added it.One of person, api_key, agent, system
media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
media.durationMsinteger or null
Videos and audio files: duration.
media.errorstring or null
Why processing failed.
media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
media.folderIdstring (uuid) or null
Folder; null for the library root.
media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
media.heightinteger or null
Pixels, once processed.
media.idstring (uuid)Required
ID.
media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
media.namestring
Name.
media.pageCountinteger or null
Documents: pages, once processed.
media.processedAtstring (date-time) or null
Processed.
media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
media.sourceUrlstring or null
Where an import came from.
media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
media.updatedAtstring (date-time)
Last change.
media.versioninteger
Increments on every change; send as expectedVersion.
media.warningsarray of objects
Provider-spec findings that don't block use.
media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
media.warnings[].messagestringRequired
Finding.
media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
media.widthinteger or null
Pixels, once processed.
notestring or null
Why there's nothing (or less) to look at.
stillsarray of objectsRequired
In order: one for an image, up to 8 frames for a video.
stills[].atstring or null
Videos: the same as a timestamp, e.g. 0:04.
stills[].atMsinteger or null
Videos: where the frame is (ms).
stills[].heightintegerRequired
Pixels.
stills[].urlstringRequired
Short-lived URL of the JPEG.
stills[].widthintegerRequired
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-After seconds. 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"