API reference

Media folders

Folders in the media library.

GET/media/folders

List folders

Permission: read

Parameters

NameTypeRequiredDescription
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
Folders by name.
items[].createdAtstring (date-time)
Created.
items[].idstring (uuid)Required
ID.
items[].mediaCountinteger
Unarchived media in it.
items[].namestring
Name.
items[].updatedAtstring (date-time)
Last change.
items[].versioninteger
Increments on every change; send as expectedVersion.

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/folders" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/media/folders

Create a folder

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

idstring (uuid)
Optional ID.
namestringRequired
Name.

Response200 OK

createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
mediaCountinteger
Unarchived media in it.
namestring
Name.
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

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/folders" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 053c6b2a-48ea-4c9c-b975-ffafec626c83" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
    "name": "vitamin-c-serum-ugc-9x16.mp4"
  }'
PATCH/media/folders/{id}

Rename a folder

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe folder'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.
namestringRequired
Name.

Response200 OK

createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
mediaCountinteger
Unarchived media in it.
namestring
Name.
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

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/folders/ab9477f7-881a-493c-a181-28d841376527" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: ceb7071d-fe46-4a39-9d16-54ffa3d9314a" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "name": "vitamin-c-serum-ugc-9x16.mp4"
  }'
DELETE/media/folders/{id}

Delete a folder

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe folder'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.

Response204 No Content

Done; no content.

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 DELETE "$PLUTO_API/media/folders/ab9477f7-881a-493c-a181-28d841376527" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3f24dc98-357a-4978-9d83-192a7e7dcf71"