Media folders
Folders in the media library.
List folders
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Folders by name.
items[].createdAt- Created.
items[].id- ID.
items[].mediaCount- Unarchived media in it.
items[].name- Name.
items[].updatedAt- Last change.
items[].version- Increments on every change; send as
expectedVersion.
curl "$PLUTO_API/media/folders" \
-H "Authorization: Bearer $PLUTO_KEY"Create a folder
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
id- Optional ID.
name- Name.
Response
createdAt- Created.
id- ID.
mediaCount- Unarchived media in it.
name- Name.
updatedAt- Last change.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/media/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"
}'Rename a folder
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The folder's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
name- Name.
Response
createdAt- Created.
id- ID.
mediaCount- Unarchived media in it.
name- Name.
updatedAt- Last change.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/media/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 a folder
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The folder's ID. |
expectedVersion | string | Optional | Version. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/media/folders/ab9477f7-881a-493c-a181-28d841376527" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3f24dc98-357a-4978-9d83-192a7e7dcf71"