Workspaces
The current workspace and its logo, and an organization's workspaces.
Get the current workspace
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
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
version- Increments on every change; send as
expectedVersion.
curl "$PLUTO_API/workspace" \
-H "Authorization: Bearer $PLUTO_KEY"Update the workspace
Changes the name, "Share new launches with guests", "Add files to Creative Memory" or any of them; fields left out stay. A new name needs expectedVersion. With shareNewLaunchesWithGuests: true, every launch created from now on starts shared with the workspace's guests, whoever creates it; launches that exist keep their own sharing (PATCH /launches/{id} sharedWithGuests). analyzeAutomatically sets when files are added to Creative Memory without being asked: used_in_ad (the default, "When an ad goes live": the files of every ad that runs at its platform, and of ads that spent in the last 90 days; a file only in drafts, or only in ads that haven't run or spent in 90 days, isn't added), every_upload (also as soon as an upload is ready) or on_request (never on its own: a person adds files in Media with Add to Creative Memory, or asks the Agent). Creative Memory is an Enterprise add-on: adding a file draws credits from the organization's pool, 250 per started video minute and 50 per image, then bought credits and auto top-up; when they run out it waits until the credits reset or more are bought. A file's content is added on its own at most once. Search is always included. businessType is how the workspace sells, so Pluto's advice fits it: ecommerce, retail (retail and consumer goods), software (software and apps), lead_generation (lead generation and local services) or unknown; until someone sets it, Pluto fills it in from the connected store and the ads.
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
analyzeAutomatically- When files are added to Creative Memory without being asked.One of
used_in_ad,every_upload,on_request businessType- How the workspace sells;
unknownclears it.One ofecommerce,retail,software,lead_generation,unknown expectedVersion- The version you last read; needed with
name. A mismatch is a conflict that returns the current workspace. name- Up to 80 characters.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests.
slug- The Workspace URL (
app.plutoads.ai/<slug>/…): 3 to 48 lowercase letters, numbers and hyphens, not starting or ending with a hyphen, not one of the app's own words (422). The old one keeps redirecting and is never another workspace's; one another workspace has or had is409("That URL is taken."). The workspace's own earlier slug can be taken back.
Response
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
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), an Idempotency-Key reused with a different request, or a Workspace URL another workspace has or had ("That URL is taken.",errors[0].fieldisslug). - 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/workspace" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c4062db1-ca76-4183-8125-f83267b67db3" \
-H "Content-Type: application/json" \
-d '{
"analyzeAutomatically": "used_in_ad",
"businessType": "ecommerce",
"expectedVersion": 3,
"name": "Brevanne",
"shareNewLaunchesWithGuests": true,
"slug": "https://brevanne.com/products/vitamin-c-serum"
}'Set the uploaded logo
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
objectKey- From /workspace/logo/upload-url.
Response
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
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 PUT "$PLUTO_API/workspace/logo" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b9afcbf4-3214-403b-9423-f572de55b79c" \
-H "Content-Type: application/json" \
-d '{
"objectKey": "fall-2026/vitamin-c-serum-ugc-9x16.mp4"
}'Remove the logo
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. |
Response
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
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 DELETE "$PLUTO_API/workspace/logo" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 01e374ef-cc44-40ea-be60-e335b62b3d3c"Start a logo upload
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. |
Request body
byteSize- Up to 2 MB.
contentType- Type.One of
image/png,image/jpeg,image/webp
Response
url, headers, objectKey.
curl -X POST "$PLUTO_API/workspace/logo/upload-url" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"byteSize": 18432000,
"contentType": "image/png"
}'Create another workspace
Sessions only. Whoever creates the organization's workspaces (organization:workspaces: its owners and admins) adds it to the current workspace's organization (as POST /organizations/{id}/workspaces does); anyone else with write gets a new organization of their own, which they own. Guests get 403, naming ads:read. API keys and agents use POST /organizations/{id}/workspaces or the MCP create_workspace tool, which need organization.
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
name- Up to 80 characters.
Response
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
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/workspaces" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: c27ccc86-1443-4aaf-830a-d2227ad628c0" \
-H "Content-Type: application/json" \
-d '{
"name": "Brevanne"
}'Check a Workspace URL
Whether the current workspace may take slug as its Workspace URL, for a live check while an admin types: available, and reason when it isn't: taken (another workspace has it now or had it), reserved (one of the app's own words) or invalid (anything not already canonical: 3 to 48 lowercase letters, numbers and hyphens, not starting or ending with a hyphen; normalize as the person types). The workspace's own current or earlier slug is available to it. Rate-limited per person.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | Optional | The slug to check. |
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
available- Whether it can be the Workspace URL.
reason- Why not; null when available.One of
taken,reserved,invalid
curl "$PLUTO_API/workspaces/slug-availability" \
-H "Authorization: Bearer $PLUTO_KEY"Upload a file for a message
Starts an upload: answers the file (uploading) and a presigned PUT for its bytes. Send the bytes with exactly the returned headers, then call complete. The type comes from the file name's extension (or contentType for a name without one) and must be one the Agent reads; each kind has its own size limit. A file that can't be attached is a 422 invalid with reason (unsupported_type, too_large, empty or bad_name), a message to show as it is and, when too large, limitBytes. A new file must fit the organization's storage: 402 plan_limit (feature media_storage) otherwise.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The workspace'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
contentType- The type the browser reports; may be empty.
name- The file's name, with its extension (1 to 255 characters).
sizeBytes- The file's exact size in bytes.
Response
filefile.children- An archive's files.
file.contentType- Its type.
file.createdAt- When it was attached.
file.durationMs- Length of a video or audio file.
file.errorfile.error.code- Why, as a stable code.
file.error.message- Why, in a sentence to show as it is.
file.id- The file.
file.kind- What it is.One of
image,video,pdf,document,spreadsheet,presentation,text,code,audio,archive file.name- Its name (an archive's file: its path in the archive).
file.pageCount- Pages (PDF, Word) or slides (PowerPoint).
file.previewUrl- A link to its preview (
GET .../preview), when it has one. file.sizeBytes- Its size in bytes.
file.statusreadyonce the Agent can read it.One ofuploading,processing,ready,faileduploadupload.expiresAt- When the URL stops working; attach the file again after.
upload.headers- Send each exactly (browsers set
HostandContent-Lengththemselves). upload.method- Always
PUT.One ofPUT upload.url- Presigned URL.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402The organization's storage is full.
- 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. - 422This file can't be attached:
reasonandmessage. - 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/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 584ef262-f3a7-482b-92c5-8f9785f3aebb" \
-H "Content-Type: application/json" \
-d '{
"contentType": "video/mp4",
"name": "Brevanne",
"sizeBytes": 18432000
}'Get an attached file
The file and its status; poll until it's ready or failed. An archive lists its files in children, each with its own status. Private to the signed-in person whose chat it is (another person's file is 404); API keys get 403 (a chat needs a person). The workspace in the path must be the one the request acts in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The workspace's ID. |
fileId | string | Required | The file's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
filefile.children- An archive's files.
file.contentType- Its type.
file.createdAt- When it was attached.
file.durationMs- Length of a video or audio file.
file.errorfile.error.code- Why, as a stable code.
file.error.message- Why, in a sentence to show as it is.
file.id- The file.
file.kind- What it is.One of
image,video,pdf,document,spreadsheet,presentation,text,code,audio,archive file.name- Its name (an archive's file: its path in the archive).
file.pageCount- Pages (PDF, Word) or slides (PowerPoint).
file.previewUrl- A link to its preview (
GET .../preview), when it has one. file.sizeBytes- Its size in bytes.
file.statusreadyonce the Agent can read it.One ofuploading,processing,ready,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5" \
-H "Authorization: Bearer $PLUTO_KEY"Finish a file's upload
Checks the uploaded bytes (their size, then that they are the file's type) and starts preparing the file for the Agent: processing, or failed with an error when the bytes aren't what the file claims. Completing a file that is past uploading answers it as it is. 409 while nothing was uploaded. Private to the signed-in person whose chat it is (another person's file is 404); API keys get 403 (a chat needs a person). The workspace in the path must be the one the request acts in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The workspace's ID. |
fileId | string | Required | The file's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
filefile.children- An archive's files.
file.contentType- Its type.
file.createdAt- When it was attached.
file.durationMs- Length of a video or audio file.
file.errorfile.error.code- Why, as a stable code.
file.error.message- Why, in a sentence to show as it is.
file.id- The file.
file.kind- What it is.One of
image,video,pdf,document,spreadsheet,presentation,text,code,audio,archive file.name- Its name (an archive's file: its path in the archive).
file.pageCount- Pages (PDF, Word) or slides (PowerPoint).
file.previewUrl- A link to its preview (
GET .../preview), when it has one. file.sizeBytes- Its size in bytes.
file.statusreadyonce the Agent can read it.One ofuploading,processing,ready,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Nothing was uploaded yet.
- 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/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5/complete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 067a1941-1e34-4e65-a1fc-61eb120c243b"Download an attached file
Redirects (302) to a short-lived URL of the original file, saved under its name. Private to the signed-in person whose chat it is (another person's file is 404); API keys get 403 (a chat needs a person). The workspace in the path must be the one the request acts in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The workspace's ID. |
fileId | string | Required | The file's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5/content" \
-H "Authorization: Bearer $PLUTO_KEY"Get a file's preview
The file's thumbnail as a JPEG (kept privately by the browser for a year: it never changes once the file is ready), so the link works as an image source: images, videos (the first frame), PDFs (the first page) and Office files that carry a thumbnail. 404 when it has none. Private to the signed-in person whose chat it is (another person's file is 404); API keys get 403 (a chat needs a person). The workspace in the path must be the one the request acts in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The workspace's ID. |
fileId | string | Required | The file's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Errors
curl "$PLUTO_API/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5/preview" \
-H "Authorization: Bearer $PLUTO_KEY"List an organization's workspaces
The workspaces the caller can open there (owners and admins every one; members and guests the ones they were given), recently opened first, then by name. The workspace switcher.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
q | string | Optional | Part of the name. |
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
canCreate- The caller may add a workspace.
included- Workspaces the plan's price includes (Pro 1, Business 10);
priceis what each one beyond them adds. items- Workspaces, recent first.
items[].current- The workspace the caller acts in.
items[].id- Workspace ID.
items[].lastOpenedAt- When the caller last opened it.
items[].logoUrl- Logo.
items[].name- Name.
items[].role- The caller's role there.One of
owner,admin,member,guest limit- The plan's workspace limit (Pro 3); null is no cap, and for anyone but owners and admins.
price- What one more adds to the bill; null when billing hasn't published prices.
price.amount- Decimal amount, e.g.
20.00. price.currency- ISO currency code, lower-case.
price.interval- Billing interval.One of
month,year upgradeTo- At the limit, the plan that holds more workspaces; null when more is agreed with Pluto instead (Enterprise terms or complimentary access), or there's no limit.One of
pro,business,enterprise used- Active workspaces in the organization; for anyone but owners and admins, the workspaces they reach.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces" \
-H "Authorization: Bearer $PLUTO_KEY"Add a workspace
Organization owners and admins, acting as a person. Everyone with access to all workspaces reaches it at once. Workspaces beyond the plan's included ones add the workspace add-on to the bill. 402 plan_limit at the plan's workspace limit (upgradeTo, nextAction), 402 payment_required while read-only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization'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
name- 1-80 characters.
Response
analyzeAutomatically- When files are added to Creative Memory without being asked: when an ad with the file goes live or spent in the last 90 days (the default), also as soon as an upload is ready, or only when someone asks (Add to Creative Memory in Media, or the Agent).One of
used_in_ad,every_upload,on_request businessType- How the workspace sells, so Pluto's advice fits it.One of
ecommerce,retail,software,lead_generation,unknown businessTypeSource- Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of
set,inferred,none createdAt- Created.
id- ID.
logoUrl- Stable logo URL; changes whenever the logo does.
name- Name.
roleCountsroleCounts.admin- Admins.
roleCounts.guest- Guests.
roleCounts.member- Members.
roleCounts.owner- Owners.
shareNewLaunchesWithGuests- New launches start shared with the workspace's guests. Off by default.
slug- The Workspace URL: its part of the app's URLs (
/<slug>/…), globally unique. suspendedCount- Suspended members.
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 POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: cea2aad5-1615-4f8a-890b-22f24770afbb" \
-H "Content-Type: application/json" \
-d '{
"name": "Brevanne"
}'List archived workspaces
Organization owners and admins. The archived workspaces and those scheduled for deletion, most recent change first: the ones that can be restored.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Archived workspaces and ones scheduled for deletion.
items[].archivedAt- When it was archived.
items[].archivedBy- Who archived it.
items[].archivedBy.id- Person.
items[].archivedBy.name- Name.
items[].canManage- The caller may archive, delete or restore it.
items[].deletionReason- Deleted on its own, or with its organization (restoring the organization restores it).One of
workspace,organization items[].deletionRequestedAt- When it was scheduled for deletion.
items[].deletionRequestedBy- Who scheduled the deletion.
items[].deletionRequestedBy.id- Person.
items[].deletionRequestedBy.name- Name.
items[].id- Workspace ID.
items[].logoUrl- Logo.
items[].name- Name.
items[].organizationId- Its organization.
items[].purgeAfter- When it's deleted for good; restorable until then.
items[].purging- Its deletion is under way (past its date), so it can't be restored any more.
items[].statusactive;archived(read-only, hidden from the switcher, all data kept);deleting(scheduled for deletion: nobody reaches it, restorable untilpurgeAfter).One ofactive,archived,deletingitems[].version- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/archived" \
-H "Authorization: Bearer $PLUTO_KEY"Get a workspace's status
Whether the workspace is active, archived or scheduled for deletion, by whom and when, and when it's deleted for good. Organization owners and admins read any workspace in the organization; members the ones they're in (a credential without the organization scope: its own). Guests get 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- When it was archived.
archivedBy- Who archived it.
archivedBy.id- Person.
archivedBy.name- Name.
canManage- The caller may archive, delete or restore it.
deletionReason- Deleted on its own, or with its organization (restoring the organization restores it).One of
workspace,organization deletionRequestedAt- When it was scheduled for deletion.
deletionRequestedBy- Who scheduled the deletion.
deletionRequestedBy.id- Person.
deletionRequestedBy.name- Name.
id- Workspace ID.
logoUrl- Logo.
name- Name.
organizationId- Its organization.
purgeAfter- When it's deleted for good; restorable until then.
purging- Its deletion is under way (past its date), so it can't be restored any more.
statusactive;archived(read-only, hidden from the switcher, all data kept);deleting(scheduled for deletion: nobody reaches it, restorable untilpurgeAfter).One ofactive,archived,deletingversion- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6" \
-H "Authorization: Bearer $PLUTO_KEY"Archive a workspace
Organization owners and admins. The workspace becomes read-only (changes answer 409 workspace_archived), leaves the switcher and the plan's workspace count, and keeps all its data, media and connections. Its loops are paused and open loop runs and queued work (publishes, scheduled publishes, imports) canceled; ads live on the ad platforms keep running. 409 for the organization's last active workspace, one already archived or one scheduled for deletion.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- When it was archived.
archivedBy- Who archived it.
archivedBy.id- Person.
archivedBy.name- Name.
canManage- The caller may archive, delete or restore it.
deletionReason- Deleted on its own, or with its organization (restoring the organization restores it).One of
workspace,organization deletionRequestedAt- When it was scheduled for deletion.
deletionRequestedBy- Who scheduled the deletion.
deletionRequestedBy.id- Person.
deletionRequestedBy.name- Name.
id- Workspace ID.
logoUrl- Logo.
name- Name.
organizationId- Its organization.
purgeAfter- When it's deleted for good; restorable until then.
purging- Its deletion is under way (past its date), so it can't be restored any more.
statusactive;archived(read-only, hidden from the switcher, all data kept);deleting(scheduled for deletion: nobody reaches it, restorable untilpurgeAfter).One ofactive,archived,deletingversion- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9af6f956-cd3d-4215-9220-5b61ae686880"Delete a workspace
Organization owners and admins, typing the workspace's exact name (422 otherwise). Schedules it for deletion: from now on members get 410 workspace_deleted (with purgeAfter), and after 30 days it's deleted for good with its media and data. Right away its API keys, agents and webhooks stop, its guests and pending invitations are removed, its ad platforms and other integrations are disconnected (nothing is revoked or deleted at the providers: ads live on the platforms keep running; what was read from a platform whose terms delete it soon after access ends, policy.retention.afterDisconnectDays on GET /platforms, goes after those days, even if the workspace is restored), its loops are paused and queued work canceled. The organization's owners are emailed. An archived workspace can be deleted too. 409 for the organization's last active workspace or one already scheduled.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace'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
confirmName- The workspace's exact name.
Response
archivedAt- When it was archived.
archivedBy- Who archived it.
archivedBy.id- Person.
archivedBy.name- Name.
canManage- The caller may archive, delete or restore it.
deletionReason- Deleted on its own, or with its organization (restoring the organization restores it).One of
workspace,organization deletionRequestedAt- When it was scheduled for deletion.
deletionRequestedBy- Who scheduled the deletion.
deletionRequestedBy.id- Person.
deletionRequestedBy.name- Name.
id- Workspace ID.
logoUrl- Logo.
name- Name.
organizationId- Its organization.
purgeAfter- When it's deleted for good; restorable until then.
purging- Its deletion is under way (past its date), so it can't be restored any more.
statusactive;archived(read-only, hidden from the switcher, all data kept);deleting(scheduled for deletion: nobody reaches it, restorable untilpurgeAfter).One ofactive,archived,deletingversion- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: cf983797-d88c-4e3f-b6ef-e42263b35c59" \
-H "Content-Type: application/json" \
-d '{
"confirmName": "Brevanne"
}'Export a workspace's ads as CSV
Export a workspace's launches, ad sets and ads as CSV.
Organization owners and admins (a credential needs the organization scope), for any workspace of the organization: active, archived or scheduled for deletion. One row per launch, then its ad sets, each followed by its ads (Type is launch, ad_set or ad): names, status, delivery, budget as a decimal string with its currency and period, the ad platform and what runs there (Platform, Platform ID, Platform status, Platform budget, Platform budget period, Platform budget currency), ad account, created, updated and archived times (RFC 3339) and Pluto IDs. The file starts with a UTF-8 byte order mark, so Excel reads accented and non-Latin letters correctly; a program reading it skips the mark (utf-8-sig in Python). RFC 4180 with CRLF line ends: a number (a budget, a numeric platform ID) as it is, other text always quoted, an empty cell empty, and a ' in front of a =, +, -, @, tab or carriage return that starts a cell, or that follows a comma, semicolon, tab or line break inside one, even after spaces or quotes, so no spreadsheet runs it as a formula, whatever its list separator. Sent as an attachment, streamed as it's written (no Content-Length). The same file as POST /organizations/{id}/workspaces/{workspace_id}/exports, which writes it in the background, follows its progress and notifies when it's ready; prefer that for a large workspace. Each export is recorded in the workspace's activity.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
CSV (text/csv; charset=utf-8). text/csv.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/export/ads.csv" \
-H "Authorization: Bearer $PLUTO_KEY"Export a workspace's media
Organization owners and admins (a credential needs the organization scope), for any workspace of the organization: active, archived or scheduled for deletion. The original of every media item that isn't deleted, streamed as it's read (no size limit, no Content-Length), stored uncompressed in a zip64 archive. File names are the media names, made safe for every system and unique (Hero (2).png). A file that can't be read from storage is left out and listed with the reason in missing.txt in the archive. Each export is recorded in the workspace's activity.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
A zip archive (application/zip). application/zip.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/export/media.zip" \
-H "Authorization: Bearer $PLUTO_KEY"Start a workspace export
Export a workspace's launches, ad sets and ads in the background.
Starts a CSV export of the workspace's launches, ad sets and ads (the same file as GET …/export/ads.csv; gzip: true for .csv.gz) and answers 202 with the export. It runs in the background: the job (jobId) counts the rows, then writes every one of them, and rowsWritten of rowsTotal says how far it got. Read it with GET /exports/{id}, which gives downloadUrl once it's done; downloads end 7 days later. Asking again for the same workspace while its export is queued or running returns that one. The person who asked gets an Inbox notice when it's ready, and an email too when it ran longer than 30 seconds or holds more than 250,000 rows (emailWhenReady). Recorded in the exported workspace's activity once the file is written (workspace.exported). Organization owners and admins (a credential needs the organization scope), for any workspace of the organization (active, archived or scheduled for deletion), asked from an active one: the export runs there (another organization's workspace, or one that isn't active, is a 409). The media originals stay a streamed download: GET …/export/media.zip.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace'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
gzip- Compress the file with gzip (
.csv.gz).
Response
bom- The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
bytes- The file's size, once written.
createdAt- When it was asked for.
downloadUrl- A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReady- It runs longer than 30 seconds or holds more than 250,000 rows, or the app's page that asked for it was left before it was ready: the person who asked also gets an email when it's ready.
error- Why it failed.
expired- Past
expiresAt: the file is gone. expiresAt- When downloads end: 7 days after it was written.
fileName- The file's name.
filters- What it applies, as checked.
finishedAt- When it was written, or failed.
gzip- The file is gzipped (
.csv.gz). id- The export.
jobId- The job that writes it: follow it with
GET /jobs/{id}(MCPwait_for_job). kind- What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of
audit_log,workspace,usage organizationId- The organization it's of; null for a workspace's audit log.
rowsTotal- The rows it holds, once counted (null before); the file's own count once it's written.
rowsWritten- The rows in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failedworkspaceId- The workspace a workspace export is of; null for other kinds.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409
conflict: asked from a workspace that isn't an active one of the organization, 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/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/exports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2af4e61f-6330-4637-9c96-de006139cfb8" \
-H "Content-Type: application/json" \
-d '{
"gzip": true
}'Restore a workspace
Organization owners and admins. Brings an archived workspace, or one scheduled for deletion, back to where it was (one archived before its deletion comes back archived). Coming back active counts toward the plan's workspace limit: 402 plan_limit at the limit. Loops stay paused until someone turns them on; revoked credentials, removed guests and disconnected integrations aren't restored. 409 for an active workspace, one whose deletion is already under way (purging), or one whose organization is scheduled for deletion (restore the organization instead).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archivedAt- When it was archived.
archivedBy- Who archived it.
archivedBy.id- Person.
archivedBy.name- Name.
canManage- The caller may archive, delete or restore it.
deletionReason- Deleted on its own, or with its organization (restoring the organization restores it).One of
workspace,organization deletionRequestedAt- When it was scheduled for deletion.
deletionRequestedBy- Who scheduled the deletion.
deletionRequestedBy.id- Person.
deletionRequestedBy.name- Name.
id- Workspace ID.
logoUrl- Logo.
name- Name.
organizationId- Its organization.
purgeAfter- When it's deleted for good; restorable until then.
purging- Its deletion is under way (past its date), so it can't be restored any more.
statusactive;archived(read-only, hidden from the switcher, all data kept);deleting(scheduled for deletion: nobody reaches it, restorable untilpurgeAfter).One ofactive,archived,deletingversion- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit: the plan's workspace limit is reached;payment_requiredwhile read-only. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/restore" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b114b905-7ca2-4d43-b7d3-d2d88bb9a2ca"