API reference

Workspaces

The current workspace and its logo, and an organization's workspaces.

GET/workspace

Get the current workspace

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

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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/workspace" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/workspace

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.

Permission: adminCommand: 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

analyzeAutomaticallystring
When files are added to Creative Memory without being asked.One of used_in_ad, every_upload, on_request
businessTypestring
How the workspace sells; unknown clears it.One of ecommerce, retail, software, lead_generation, unknown
expectedVersioninteger
The version you last read; needed with name. A mismatch is a conflict that returns the current workspace.
namestring
Up to 80 characters.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests.
slugstring
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 is 409 ("That URL is taken."). The workspace's own earlier slug can be taken back.

Response200 OK

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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), an Idempotency-Key reused with a different request, or a Workspace URL another workspace has or had ("That URL is taken.", errors[0].field is slug).
  • 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/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"
  }'
PUT/workspace/logo
Permission: adminCommand: 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

objectKeystringRequired
From /workspace/logo/upload-url.

Response200 OK

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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 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"
  }'
DELETE/workspace/logo
Permission: adminCommand: 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.

Response200 OK

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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 DELETE "$PLUTO_API/workspace/logo" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 01e374ef-cc44-40ea-be60-e335b62b3d3c"
POST/workspace/logo/upload-url

Start a logo upload

Permission: admin

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.

Request body

byteSizeintegerRequired
Up to 2 MB.
contentTypestringRequired
Type.One of image/png, image/jpeg, image/webp

Response200 OK

url, headers, objectKey.

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 -X POST "$PLUTO_API/workspace/logo/upload-url" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "byteSize": 18432000,
    "contentType": "image/png"
  }'
POST/workspaces

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.

Permission: writeApp session onlyCommand: 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

namestringRequired
Up to 80 characters.

Response201 Created

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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/workspaces" \
  -b "plutoads_session=$PLUTO_SESSION" \
  -H "Idempotency-Key: c27ccc86-1443-4aaf-830a-d2227ad628c0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brevanne"
  }'
GET/workspaces/slug-availability

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.

Permission: admin

Parameters

NameTypeRequiredDescription
slugquerystringOptionalThe slug to check.
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

availablebooleanRequired
Whether it can be the Workspace URL.
reasonstring or nullRequired
Why not; null when available.One of taken, reserved, invalid

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/workspaces/slug-availability" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/workspaces/{id}/chat-files

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe workspace'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

contentTypestringRequired
The type the browser reports; may be empty.
namestringRequired
The file's name, with its extension (1 to 255 characters).
sizeBytesintegerRequired
The file's exact size in bytes.

Response201 Created

fileobjectRequired
file.childrenarray of objects
An archive's files.
file.contentTypestringRequired
Its type.
file.createdAtstring (date-time)Required
When it was attached.
file.durationMsinteger or null
Length of a video or audio file.
file.errorobject
file.error.codestringRequired
Why, as a stable code.
file.error.messagestringRequired
Why, in a sentence to show as it is.
file.idstring (uuid)Required
The file.
file.kindstringRequired
What it is.One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
file.namestringRequired
Its name (an archive's file: its path in the archive).
file.pageCountinteger or null
Pages (PDF, Word) or slides (PowerPoint).
file.previewUrlstring or null
A link to its preview (GET .../preview), when it has one.
file.sizeBytesintegerRequired
Its size in bytes.
file.statusstringRequired
ready once the Agent can read it.One of uploading, processing, ready, failed
uploadobjectRequired
upload.expiresAtstring (date-time)Required
When the URL stops working; attach the file again after.
upload.headersmap of stringRequired
Send each exactly (browsers set Host and Content-Length themselves).
upload.methodstringRequired
Always PUT.One of PUT
upload.urlstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422This file can't be attached: reason and message.
  • 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/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/workspaces/{id}/chat-files/{fileId}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe workspace's ID.
fileIdpathstringRequiredThe file'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

fileobjectRequired
file.childrenarray of objects
An archive's files.
file.contentTypestringRequired
Its type.
file.createdAtstring (date-time)Required
When it was attached.
file.durationMsinteger or null
Length of a video or audio file.
file.errorobject
file.error.codestringRequired
Why, as a stable code.
file.error.messagestringRequired
Why, in a sentence to show as it is.
file.idstring (uuid)Required
The file.
file.kindstringRequired
What it is.One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
file.namestringRequired
Its name (an archive's file: its path in the archive).
file.pageCountinteger or null
Pages (PDF, Word) or slides (PowerPoint).
file.previewUrlstring or null
A link to its preview (GET .../preview), when it has one.
file.sizeBytesintegerRequired
Its size in bytes.
file.statusstringRequired
ready once the Agent can read it.One of uploading, 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-After seconds. 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"
POST/workspaces/{id}/chat-files/{fileId}/complete

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe workspace's ID.
fileIdpathstringRequiredThe file'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

fileobjectRequired
file.childrenarray of objects
An archive's files.
file.contentTypestringRequired
Its type.
file.createdAtstring (date-time)Required
When it was attached.
file.durationMsinteger or null
Length of a video or audio file.
file.errorobject
file.error.codestringRequired
Why, as a stable code.
file.error.messagestringRequired
Why, in a sentence to show as it is.
file.idstring (uuid)Required
The file.
file.kindstringRequired
What it is.One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
file.namestringRequired
Its name (an archive's file: its path in the archive).
file.pageCountinteger or null
Pages (PDF, Word) or slides (PowerPoint).
file.previewUrlstring or null
A link to its preview (GET .../preview), when it has one.
file.sizeBytesintegerRequired
Its size in bytes.
file.statusstringRequired
ready once the Agent can read it.One of uploading, 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; 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/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"
GET/workspaces/{id}/chat-files/{fileId}/content

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe workspace's ID.
fileIdpathstringRequiredThe file'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.

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/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5/content" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/workspaces/{id}/chat-files/{fileId}/preview

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe workspace's ID.
fileIdpathstringRequiredThe file'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.

Response302 Found

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404The file has no preview.
  • 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/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6/chat-files/1407e6a7-8e94-4479-98ab-d5432626c5a5/preview" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/organizations/{id}/workspaces

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.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
qquerystringOptionalPart of the name.
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

canCreatebooleanRequired
The caller may add a workspace.
includedinteger or null
Workspaces the plan's price includes (Pro 1, Business 10); price is what each one beyond them adds.
itemsarray of objectsRequired
Workspaces, recent first.
items[].currentbooleanRequired
The workspace the caller acts in.
items[].idstring (uuid)Required
Workspace ID.
items[].lastOpenedAtstring (date-time) or null
When the caller last opened it.
items[].logoUrlstring or null
Logo.
items[].namestringRequired
Name.
items[].rolestring or null
The caller's role there.One of owner, admin, member, guest
limitinteger or null
The plan's workspace limit (Pro 3); null is no cap, and for anyone but owners and admins.
priceobject or null
What one more adds to the bill; null when billing hasn't published prices.
price.amountstringRequired
Decimal amount, e.g. 20.00.
price.currencystringRequired
ISO currency code, lower-case.
price.intervalstringRequired
Billing interval.One of month, year
upgradeTostring or null
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
usedintegerRequired
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-After seconds. 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"
POST/organizations/{id}/workspaces

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization'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

namestringRequired
1-80 characters.

Response201 Created

analyzeAutomaticallystring
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
businessTypestring
How the workspace sells, so Pluto's advice fits it.One of ecommerce, retail, software, lead_generation, unknown
businessTypeSourcestring
Who decided it: a person or the Agent, Pluto from the connected store and the ads, or nobody yet.One of set, inferred, none
createdAtstring (date-time)
Created.
idstring (uuid)Required
ID.
logoUrlstring or null
Stable logo URL; changes whenever the logo does.
namestring
Name.
roleCountsobject
roleCounts.adminintegerRequired
Admins.
roleCounts.guestintegerRequired
Guests.
roleCounts.memberintegerRequired
Members.
roleCounts.ownerintegerRequired
Owners.
shareNewLaunchesWithGuestsboolean
New launches start shared with the workspace's guests. Off by default.
slugstring or null
The Workspace URL: its part of the app's URLs (/<slug>/…), globally unique.
suspendedCountinteger
Suspended members.
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 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"
  }'
GET/organizations/{id}/workspaces/archived

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization'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

itemsarray of objectsRequired
Archived workspaces and ones scheduled for deletion.
items[].archivedAtstring (date-time) or nullRequired
When it was archived.
items[].archivedByobject or nullRequired
Who archived it.
items[].archivedBy.idstring (uuid)Required
Person.
items[].archivedBy.namestringRequired
Name.
items[].canManagebooleanRequired
The caller may archive, delete or restore it.
items[].deletionReasonstring or nullRequired
Deleted on its own, or with its organization (restoring the organization restores it).One of workspace, organization
items[].deletionRequestedAtstring (date-time) or nullRequired
When it was scheduled for deletion.
items[].deletionRequestedByobject or nullRequired
Who scheduled the deletion.
items[].deletionRequestedBy.idstring (uuid)Required
Person.
items[].deletionRequestedBy.namestringRequired
Name.
items[].idstring (uuid)Required
Workspace ID.
items[].logoUrlstring or nullRequired
Logo.
items[].namestringRequired
Name.
items[].organizationIdstring (uuid)Required
Its organization.
items[].purgeAfterstring (date-time) or nullRequired
When it's deleted for good; restorable until then.
items[].purgingbooleanRequired
Its deletion is under way (past its date), so it can't be restored any more.
items[].statusstringRequired
active; archived (read-only, hidden from the switcher, all data kept); deleting (scheduled for deletion: nobody reaches it, restorable until purgeAfter).One of active, archived, deleting
items[].versionintegerRequired
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-After seconds. 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/organizations/{id}/workspaces/{workspace_id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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 nullRequired
When it was archived.
archivedByobject or nullRequired
Who archived it.
archivedBy.idstring (uuid)Required
Person.
archivedBy.namestringRequired
Name.
canManagebooleanRequired
The caller may archive, delete or restore it.
deletionReasonstring or nullRequired
Deleted on its own, or with its organization (restoring the organization restores it).One of workspace, organization
deletionRequestedAtstring (date-time) or nullRequired
When it was scheduled for deletion.
deletionRequestedByobject or nullRequired
Who scheduled the deletion.
deletionRequestedBy.idstring (uuid)Required
Person.
deletionRequestedBy.namestringRequired
Name.
idstring (uuid)Required
Workspace ID.
logoUrlstring or nullRequired
Logo.
namestringRequired
Name.
organizationIdstring (uuid)Required
Its organization.
purgeAfterstring (date-time) or nullRequired
When it's deleted for good; restorable until then.
purgingbooleanRequired
Its deletion is under way (past its date), so it can't be restored any more.
statusstringRequired
active; archived (read-only, hidden from the switcher, all data kept); deleting (scheduled for deletion: nobody reaches it, restorable until purgeAfter).One of active, archived, deleting
versionintegerRequired
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-After seconds. 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"
POST/organizations/{id}/workspaces/{workspace_id}/archive

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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 nullRequired
When it was archived.
archivedByobject or nullRequired
Who archived it.
archivedBy.idstring (uuid)Required
Person.
archivedBy.namestringRequired
Name.
canManagebooleanRequired
The caller may archive, delete or restore it.
deletionReasonstring or nullRequired
Deleted on its own, or with its organization (restoring the organization restores it).One of workspace, organization
deletionRequestedAtstring (date-time) or nullRequired
When it was scheduled for deletion.
deletionRequestedByobject or nullRequired
Who scheduled the deletion.
deletionRequestedBy.idstring (uuid)Required
Person.
deletionRequestedBy.namestringRequired
Name.
idstring (uuid)Required
Workspace ID.
logoUrlstring or nullRequired
Logo.
namestringRequired
Name.
organizationIdstring (uuid)Required
Its organization.
purgeAfterstring (date-time) or nullRequired
When it's deleted for good; restorable until then.
purgingbooleanRequired
Its deletion is under way (past its date), so it can't be restored any more.
statusstringRequired
active; archived (read-only, hidden from the switcher, all data kept); deleting (scheduled for deletion: nobody reaches it, restorable until purgeAfter).One of active, archived, deleting
versionintegerRequired
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 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/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"
POST/organizations/{id}/workspaces/{workspace_id}/delete

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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

confirmNamestringRequired
The workspace's exact name.

Response200 OK

archivedAtstring (date-time) or nullRequired
When it was archived.
archivedByobject or nullRequired
Who archived it.
archivedBy.idstring (uuid)Required
Person.
archivedBy.namestringRequired
Name.
canManagebooleanRequired
The caller may archive, delete or restore it.
deletionReasonstring or nullRequired
Deleted on its own, or with its organization (restoring the organization restores it).One of workspace, organization
deletionRequestedAtstring (date-time) or nullRequired
When it was scheduled for deletion.
deletionRequestedByobject or nullRequired
Who scheduled the deletion.
deletionRequestedBy.idstring (uuid)Required
Person.
deletionRequestedBy.namestringRequired
Name.
idstring (uuid)Required
Workspace ID.
logoUrlstring or nullRequired
Logo.
namestringRequired
Name.
organizationIdstring (uuid)Required
Its organization.
purgeAfterstring (date-time) or nullRequired
When it's deleted for good; restorable until then.
purgingbooleanRequired
Its deletion is under way (past its date), so it can't be restored any more.
statusstringRequired
active; archived (read-only, hidden from the switcher, all data kept); deleting (scheduled for deletion: nobody reaches it, restorable until purgeAfter).One of active, archived, deleting
versionintegerRequired
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 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/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"
  }'
GET/organizations/{id}/workspaces/{workspace_id}/export/ads.csv

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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

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-After seconds. 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"
GET/organizations/{id}/workspaces/{workspace_id}/export/media.zip

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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

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-After seconds. 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"
POST/organizations/{id}/workspaces/{workspace_id}/exports

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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

gzipboolean
Compress the file with gzip (.csv.gz).

Response202 Accepted

bombooleanRequired
The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
bytesinteger or nullRequired
The file's size, once written.
createdAtstring (date-time)Required
When it was asked for.
downloadUrlstring or nullRequired
A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReadybooleanRequired
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.
errorstring or nullRequired
Why it failed.
expiredbooleanRequired
Past expiresAt: the file is gone.
expiresAtstring (date-time) or nullRequired
When downloads end: 7 days after it was written.
fileNamestringRequired
The file's name.
filtersobjectRequired
What it applies, as checked.
finishedAtstring (date-time) or nullRequired
When it was written, or failed.
gzipbooleanRequired
The file is gzipped (.csv.gz).
idstring (uuid)Required
The export.
jobIdstring (uuid) or nullRequired
The job that writes it: follow it with GET /jobs/{id} (MCP wait_for_job).
kindstringRequired
What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of audit_log, workspace, usage
organizationIdstring (uuid) or nullRequired
The organization it's of; null for a workspace's audit log.
rowsTotalinteger or nullRequired
The rows it holds, once counted (null before); the file's own count once it's written.
rowsWrittenintegerRequired
The rows in the file so far.
statusstringRequired
done: the file is written and can be downloaded until expiresAt.One of queued, running, done, failed
workspaceIdstring (uuid) or nullRequired
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.
  • 409conflict: asked from a workspace that isn't an active one of the organization, 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/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
  }'
POST/organizations/{id}/workspaces/{workspace_id}/restore

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

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace'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 nullRequired
When it was archived.
archivedByobject or nullRequired
Who archived it.
archivedBy.idstring (uuid)Required
Person.
archivedBy.namestringRequired
Name.
canManagebooleanRequired
The caller may archive, delete or restore it.
deletionReasonstring or nullRequired
Deleted on its own, or with its organization (restoring the organization restores it).One of workspace, organization
deletionRequestedAtstring (date-time) or nullRequired
When it was scheduled for deletion.
deletionRequestedByobject or nullRequired
Who scheduled the deletion.
deletionRequestedBy.idstring (uuid)Required
Person.
deletionRequestedBy.namestringRequired
Name.
idstring (uuid)Required
Workspace ID.
logoUrlstring or nullRequired
Logo.
namestringRequired
Name.
organizationIdstring (uuid)Required
Its organization.
purgeAfterstring (date-time) or nullRequired
When it's deleted for good; restorable until then.
purgingbooleanRequired
Its deletion is under way (past its date), so it can't be restored any more.
statusstringRequired
active; archived (read-only, hidden from the switcher, all data kept); deleting (scheduled for deletion: nobody reaches it, restorable until purgeAfter).One of active, archived, deleting
versionintegerRequired
Version.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_limit: the plan's workspace limit is reached; payment_required while read-only.
  • 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/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"