Organization
Organizations, their people, invitations and credentials.
List organizations
The organizations the caller reaches: a person every organization they belong to; an API key or agent only its workspace's. current marks the one the caller acts in.
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
currentOrganizationId- The organization the caller acts in.
items- Organizations by name.
items[].audience- Who it's for.One of
brand,multi_brand,agency items[].current- The organization the caller acts in.
items[].id- Organization ID.
items[].name- Name.
items[].role- The caller's role.One of
owner,admin,member,guest items[].slug- Slug.
items[].statusdeletingwhile scheduled for deletion.One ofactive,deletingitems[].workspaceCount- Workspaces the caller can open there.
curl "$PLUTO_API/organizations" \
-H "Authorization: Bearer $PLUTO_KEY"Get an organization
404 for an organization the caller doesn't reach.
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
audience- Who it's for: tunes copy and suggestions, never structure.One of
brand,multi_brand,agency createdAt- Created.
credentialPolicy- What members may do with credentials beyond their role (Organization › Security).
credentialPolicy.allowHandOver- Whoever removes someone may take over their API keys and service agent clients, each re-issued to them with a new secret; false: a leaving person's are always revoked, and taking them over is refused. Binds owners and admins too. True until turned off.
credentialPolicy.maxLifetimeDays- New API keys, agent clients and agent connections members make end within this many days (1-730); null: no limit, and never is allowed.
credentialPolicy.membersAgentAccess- What members' own agents may do:
full(up to their role),build(build and publish: view, launches and drafts, media, reviews, publishing, live budgets, pausing and resuming) orview(only view). Narrows their agents on their next request.One offull,build,view credentialPolicy.membersAgentClientAccess- What agent clients members are accountable for may do,
mcpandm2malike:full,buildorview, asmembersAgentAccess. Narrows their clients on their next request; their scopes stay.One offull,build,view credentialPolicy.membersApiKeyAccess- What API keys members are accountable for may do:
full,buildorview, asmembersAgentAccess. Narrows their keys on their next request; their scopes stay.One offull,build,view credentialPolicy.membersMayCreateAgentClients- Members may register agent clients when their role lets them; false: only the organization's owners and admins do. Clients made before keep working.
credentialPolicy.membersMayCreateApiKeys- Members may create API keys when their role lets them; false: only the organization's owners and admins do. Keys made before keep working.
credentialPolicy.membersMayCreateWebhooks- Members may create webhooks when their role lets them; false: only the organization's owners and admins do. Webhooks made before keep delivering.
guests- Active guests (free); null for anyone but owners and admins.
id- Organization ID.
members- Paid seats (active members who aren't guests); null for anyone but owners and admins.
membersCanConnectAgents- Members (not only owners and admins) can connect agents for themselves.
name- Name, 1-80 characters.
ownerId- Who created it.
purgeAfter- When it's deleted for good, while scheduled for deletion.
role- The caller's role; null for a credential without a person in it.One of
owner,admin,member,guest slug- Unique, 3-48 lowercase letters, digits and hyphens.
statusdeletingwhile scheduled for deletion (an owner can restore it untilpurgeAfter).One ofactive,deletingversion- Version for
expectedVersion. workspaceCount- Workspaces in it for owners and admins; for anyone else, the ones they can open.
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" \
-H "Authorization: Bearer $PLUTO_KEY"Update an organization
Organization owners and admins. Changes the name, slug, audience (null clears it), whether members can connect agents, or the credential policy for members.
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
audience- Who it's for;
nullclears it.One ofbrand,multi_brand,agency credentialPolicy- The credential policy for members (Organization › Security): each setting you leave out keeps its value. Owners and admins aren't bound by it.
credentialPolicy.allowHandOver- Whoever removes someone may take over their API keys and service agent clients, each re-issued to them with a new secret; false: a leaving person's are always revoked, and taking them over is refused. Binds owners and admins too. True until turned off.
credentialPolicy.maxLifetimeDays- New API keys, agent clients and agent connections members make end within this many days (1-730); null: no limit, and never is allowed.
credentialPolicy.membersAgentAccess- What members' own agents may do:
full(up to their role),build(build and publish: view, launches and drafts, media, reviews, publishing, live budgets, pausing and resuming) orview(only view). Narrows their agents on their next request.One offull,build,view credentialPolicy.membersAgentClientAccess- What agent clients members are accountable for may do,
mcpandm2malike:full,buildorview, asmembersAgentAccess. Narrows their clients on their next request; their scopes stay.One offull,build,view credentialPolicy.membersApiKeyAccess- What API keys members are accountable for may do:
full,buildorview, asmembersAgentAccess. Narrows their keys on their next request; their scopes stay.One offull,build,view credentialPolicy.membersMayCreateAgentClients- Members may register agent clients when their role lets them; false: only the organization's owners and admins do. Clients made before keep working.
credentialPolicy.membersMayCreateApiKeys- Members may create API keys when their role lets them; false: only the organization's owners and admins do. Keys made before keep working.
credentialPolicy.membersMayCreateWebhooks- Members may create webhooks when their role lets them; false: only the organization's owners and admins do. Webhooks made before keep delivering.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
membersCanConnectAgents- Members (not only owners and admins) can connect agents for themselves. Off stops members' connected agents on their next request.
name- 1-80 characters.
slug- Unique, 3-48 lowercase letters, digits and hyphens.
Response
audience- Who it's for: tunes copy and suggestions, never structure.One of
brand,multi_brand,agency createdAt- Created.
credentialPolicy- What members may do with credentials beyond their role (Organization › Security).
credentialPolicy.allowHandOver- Whoever removes someone may take over their API keys and service agent clients, each re-issued to them with a new secret; false: a leaving person's are always revoked, and taking them over is refused. Binds owners and admins too. True until turned off.
credentialPolicy.maxLifetimeDays- New API keys, agent clients and agent connections members make end within this many days (1-730); null: no limit, and never is allowed.
credentialPolicy.membersAgentAccess- What members' own agents may do:
full(up to their role),build(build and publish: view, launches and drafts, media, reviews, publishing, live budgets, pausing and resuming) orview(only view). Narrows their agents on their next request.One offull,build,view credentialPolicy.membersAgentClientAccess- What agent clients members are accountable for may do,
mcpandm2malike:full,buildorview, asmembersAgentAccess. Narrows their clients on their next request; their scopes stay.One offull,build,view credentialPolicy.membersApiKeyAccess- What API keys members are accountable for may do:
full,buildorview, asmembersAgentAccess. Narrows their keys on their next request; their scopes stay.One offull,build,view credentialPolicy.membersMayCreateAgentClients- Members may register agent clients when their role lets them; false: only the organization's owners and admins do. Clients made before keep working.
credentialPolicy.membersMayCreateApiKeys- Members may create API keys when their role lets them; false: only the organization's owners and admins do. Keys made before keep working.
credentialPolicy.membersMayCreateWebhooks- Members may create webhooks when their role lets them; false: only the organization's owners and admins do. Webhooks made before keep delivering.
guests- Active guests (free); null for anyone but owners and admins.
id- Organization ID.
members- Paid seats (active members who aren't guests); null for anyone but owners and admins.
membersCanConnectAgents- Members (not only owners and admins) can connect agents for themselves.
name- Name, 1-80 characters.
ownerId- Who created it.
purgeAfter- When it's deleted for good, while scheduled for deletion.
role- The caller's role; null for a credential without a person in it.One of
owner,admin,member,guest slug- Unique, 3-48 lowercase letters, digits and hyphens.
statusdeletingwhile scheduled for deletion (an owner can restore it untilpurgeAfter).One ofactive,deletingversion- Version for
expectedVersion. workspaceCount- Workspaces in it for owners and admins; for anyone else, the ones they can open.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 84a3024c-d367-4d1d-9d97-552cbcdf60af" \
-H "Content-Type: application/json" \
-d '{
"audience": "brand",
"credentialPolicy": {
"allowHandOver": false,
"maxLifetimeDays": 7,
"membersAgentAccess": "full",
"membersAgentClientAccess": "full",
"membersApiKeyAccess": "full",
"membersMayCreateAgentClients": true,
"membersMayCreateApiKeys": true,
"membersMayCreateWebhooks": true
},
"expectedVersion": 3,
"membersCanConnectAgents": true,
"name": "Brevanne",
"slug": "brevanne"
}'Get the AI improvement setting
Help improve Pluto's AI.
Whether the organization shares usage data to improve Pluto's AI features: while on, the text of its Agent and loop AI runs is kept with their traces, redacted of secrets, for 30 days, so Pluto can find and fix failures. Never used to train models. Off by default; without it only metadata is kept. Members; guests get 403. Also in MCP as get_ai_improvement.
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
changedAt- When an owner or admin last changed it; null if never.
enabled- Whether the organization shares usage data to improve Pluto's AI.
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/ai-improvement" \
-H "Authorization: Bearer $PLUTO_KEY"Set the AI improvement setting
Turn Help improve Pluto's AI on or off.
Organization owners and admins (a credential needs the organization scope). Turning it off stops keeping text from then on; text already kept lapses within 30 days. Works while the organization is read-only: it's a privacy choice. Also in MCP as set_ai_improvement.
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
enabled- Share usage data to improve Pluto's AI.
Response
changedAt- When an owner or admin last changed it; null if never.
enabled- Whether the organization shares usage data to improve Pluto's AI.
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 PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/ai-improvement" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5913f944-25b2-4e54-b5ae-0223616f85bc" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'List an organization's log entries
What was done to the organization, newest first: its plan, billing, credits and limits, members, invitations and credentials, from whichever of its workspaces. The same entries, filters and order as GET /audit-log. Whoever reads audit logs (audit:read) and manages the organization's people (organization:members); a credential needs the organization scope. The audit log comes with Business and Enterprise: 402 plan_limit on other plans. Keyset-paged: pass nextAfter as after.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
actorKind | string | Optional | person, api_key, agent or system. |
actorId | string | Optional | A person, API key or agent. |
person | string | Optional | A person (user ID): what they did, what was done for them, and what they approved. |
origin | string | Optional | app, api_key, mcp, agent_chat, loop or system. |
originId | string | Optional | An Agent chat or a loop run. |
loopId | string | Optional | Every run of a loop. |
targetType | string | Optional | What kind of thing changed (launch, ad_set, loop, api_key, ...). |
targetId | string | Optional | One object. |
action | string | Optional | An action (launch.publish_requested), or a prefix ending in . (launch.). |
commandId | string | Optional | The entries of one command: the Idempotency-Key it was sent with. |
since | string | Optional | From this time on (RFC 3339). |
until | string | Optional | Before this time (RFC 3339). |
q | string | Optional | Words to find in names, the target, the action and the details shown. |
order | string | Optional | newest (default) or oldest first, over every page; a cursor belongs to its order. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size (1-200, default 50). |
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- Entries, newest first.
items[].action- What happened, as a stable machine name (
launch.publish_requested). Showsummaryto people instead. items[].actoritems[].actor.id- The person, API key or agent.
items[].actor.kind- Who acted.One of
person,api_key,agent,system items[].actor.name- Their name.
items[].approval- The approval that let it run, if one did.
items[].approval.approvedBy- Who approved it.
items[].approval.approvedBy.id- User ID.
items[].approval.approvedBy.name- Their name.
items[].approval.id- The approval.
items[].approval.kind- An Agent approval card, a loop's approval, or a plan (change set).One of
agent,loop,change_set items[].commandId- The command (Idempotency-Key) it belongs to.
items[].createdAt- When it happened.
items[].detail- What changed and why, where it says more than
summary:beforeandafter,changes,fields,fromandto, areason, arole,statusorscopes, anamountandcurrency, aplanorcadence, asource, and the IDs it touched (launchId,jobId, ...). Only these kinds of keys are shown, never a secret, and an email only on an entry about that invitation or person.{}when there's nothing to add. items[].id- Entry ID.
items[].onBehalfOf- The person accountable: the person themself, the person an agent acts for, an API key's creator, or a loop's owner.
items[].onBehalfOf.id- User ID.
items[].onBehalfOf.name- Their name.
items[].originitems[].origin.id- The Agent chat, or the loop run.
items[].origin.kind- Where it came from: the app, the REST API, an MCP client, the in-app Agent, a loop run, or Pluto itself.One of
app,api_key,mcp,agent_chat,loop,system items[].origin.name- The loop's name, or the chat's title when you can open the chat.
items[].origin.parentId- The loop of a loop run.
items[].requestId- The request (
x-request-id) or tool call it came from, to find it in your logs; null for entries recorded before requests were kept. items[].summary- What happened, in one human sentence with the target's name.
items[].targetitems[].target.id- Its ID (a Meta ID for objects only in Meta).
items[].target.launchId- The launch of an ad set, ad or comment.
items[].target.name- Its current name, or the one recorded.
items[].target.type- What kind of thing changed (
launch,ad_set,loop,api_key, ...). items[].workspaceId- The workspace it happened in (an organization's log spans its workspaces).
nextAfter- Pass as
afterfor the next page; null on the last.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: audit_log,upgradeTo: business): the audit log comes with Business. - 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/audit-log" \
-H "Authorization: Bearer $PLUTO_KEY"Export an organization's audit log
Starts a CSV export of the organization's audit log, as POST /audit-log/exports does for a workspace's, from one of the organization's workspaces (another organization's workspace is a 409). Whoever reads audit logs (audit:read) and manages the organization's people (organization:members); a credential needs the organization scope.
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
action- An action, or a prefix ending in
.(launch.). actorId- Only this person, API key or agent.
actorKind- Only this kind of actor.One of
person,api_key,agent,system commandId- Only the entries of this command (its Idempotency-Key).
gzip- Compress the file with gzip (
.csv.gz). loopId- Only from runs of this loop.
order- The file's order: newest first (default) or oldest.One of
newest,oldest origin- Only from this channel.One of
app,api_key,mcp,agent_chat,loop,system originId- Only from this Agent chat or loop run.
person- A person: what they did, what was done for them and what they approved.
q- Words to find in names, the target, the action and the details shown.
since- Only from this time on.
targetId- Only changes to this object.
targetType- Only changes to this kind of thing.
until- Only before this time.
Response
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 entries, 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:
audit-log-<workspace or organization>-<date>.csv. filters- The filters it applies.
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). organizationId- The organization whose log it is; null for the workspace's.
rowsTotal- The entries the filters match, once counted (null before); the file's own count once it's written.
rowsWritten- The entries in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: audit_log,upgradeTo: business): the audit log comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409
conflict: asked from another organization's workspace (open one of the organization's), 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/audit-log/exports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f6a5a7ec-9fe8-402b-bd5b-9b8b79ea1a5e" \
-H "Content-Type: application/json" \
-d '{
"action": "launch.",
"actorId": "6c125817-4e50-4eb9-8477-114ed6c3f69e",
"actorKind": "person",
"commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
"gzip": true,
"loopId": "94956d8d-acdf-4e32-b384-25d0b605c2a9",
"order": "newest",
"origin": "app",
"originId": "17f4a382-2c27-4e34-a66f-6c98e0d379dd",
"person": "917f53a3-2f30-4f02-a755-31a2d4a5799f",
"q": "vitamin c serum",
"since": "2026-09-21T14:05:00Z",
"targetId": "01af096e-7668-46f6-8a67-e1ee7742b6fc",
"targetType": "video",
"until": "2026-09-30T13:00:00Z"
}'List the organization's credentials
Organization owners and admins see every workspace's; someone who may manage everyone's credentials (credentials:manage) in some of its workspaces sees those workspaces' (403 with none). Every active API key, agent client and connected agent there: who it acts for, the workspace, its scopes, when and from where it was last used, when it was created and when it expires. Its webhooks too (kind: webhook, named by their endpoint, with the person accountable for each, its last delivery as lastUsedAt and whether it delivers now, delivering and notDelivering), and the Pluto MCP connections people consented to (kind: pluto_mcp). Most recently used first. Secrets are never returned.
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- Credentials.
items[].allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. items[].createdAt- Created.
items[].createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. items[].delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
items[].detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp items[].expiresAt- When it stops working by itself; null: never.
items[].id- Credential ID.
items[].kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp items[].lastUsedAt- Last use.
items[].lastUsedIp- The address of its last use.
items[].name- Name.
items[].notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. items[].resources- What it reaches in the workspace.
items[].resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.items[].scopes- Scopes; never more than the person's current role.
items[].userEmail- Their email.
items[].userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
items[].userName- Their name.
items[].workspaceId- The workspace it works in.
items[].workspaceName- Its name.
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/credentials" \
-H "Authorization: Bearer $PLUTO_KEY"Narrow a credential
Organization owners and admins narrow any API key, agent client or connected agent in the organization; someone who may manage everyone's credentials in some of its workspaces, those workspaces' (404 for another). It keeps its secret, client and tokens, and from its next request does only what scopes keeps: scopes it holds now or fewer, each with what it requires beside it. A scope it doesn't hold is 422: narrowing never adds access. A change is audited once, in the credential's workspace, with the scopes before and after.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
credential_id | string | Required | The credential'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
resources- The ad accounts it keeps, each one it reaches now (
allonly while it reaches every one); a wider set is422. Without it, it keeps what it reaches. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- What it keeps.
Response
allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. createdAt- Created.
createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp expiresAt- When it stops working by itself; null: never.
id- Credential ID.
kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp lastUsedAt- Last use.
lastUsedIp- The address of its last use.
name- Name.
notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. resources- What it reaches in the workspace.
resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.scopes- Scopes; never more than the person's current role.
userEmail- Their email.
userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
userName- Their name.
workspaceId- The workspace it works in.
workspaceName- Its name.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/credentials/c2eade1b-2d68-4ea0-8972-d3736b5e1527" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c93be840-8f50-4ddb-8f73-639e1be435d3" \
-H "Content-Type: application/json" \
-d '{
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Revoke a credential
Organization owners and admins revoke any API key, agent client, connected agent or Pluto MCP connection in the organization, and turn off any of its webhooks; someone who may manage everyone's credentials in some of its workspaces, those workspaces' (404 for another). Its next request is refused and its queued work stops; a webhook turned off gets no more events, for good. A credential can't revoke itself (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
credential_id | string | Required | The credential'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
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/credentials/c2eade1b-2d68-4ea0-8972-d3736b5e1527" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 56789a13-ea8d-4f69-a0db-e3beab25b73c"Delete an organization
An owner, signed in to Pluto Ads: person only, so API keys, agents and MCP clients get 403 (there's no MCP tool for it). Type the organization's name in confirmName. Schedules the organization and every workspace in it for deletion in 30 days: nobody reaches them from now on, and an owner can restore everything until purgeAfter, as long as deleting the data hasn't started. Workspaces that were already scheduled for deletion on their own keep their own date. Like deleting a workspace, it pauses loops, cancels queued work, revokes API keys and agents, removes guests and pending invitations, and disconnects its ad platforms and other integrations without changing anything at the platforms (ads already running 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). The subscription ends with the current paid period (subscriptionEndsAt), and owners get an email. Asking again while it's scheduled changes nothing. Works without a workspace, since none of the organization's is reachable.
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
confirmName- The organization's name, exactly.
Response
deletionRequestedAt- When it was scheduled for deletion.
id- Organization ID.
name- Name.
purgeAfter- When it's deleted for good (30 days after it was scheduled); restorable until then.
statusactive, ordeleting: scheduled for deletion, with every workspace in it; an owner can restore it untilpurgeAfter.One ofactive,deletingsubscriptionEndsAt- The end of the paid period, when the subscription is set to end then; null without a subscription.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not a member of this organization.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422
confirmNamedoesn't match the name. - 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/delete" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: c117b080-1c65-417c-a03d-7b79b3401e8f" \
-H "Content-Type: application/json" \
-d '{
"confirmName": "Brevanne"
}'Invite someone to the organization
Organization owners and admins. One email goes out; signing in with the address accepts it. Members reach every workspace (all, the default) or the selected ones (Business and Enterprise); admins every one; guests (free) the selected ones, to review. Pro holds up to 5 members and 10 guests, pending invitations included. Guest invitations are rate limited per organization (429).
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
email- Email.
name- Name; the part before
@when absent. role- Organization role.One of
admin,member,guest workspaceAccess- For members.One of
all,selected workspaceIds- The workspaces for
selectedaccess; required for guests.
Response
items- The invitation.
items[].createdAt- Sent.
items[].email- Invited address.
items[].expiresAt- Expires (7 days).
items[].id- Invitation ID.
items[].name- Name.
items[].role- The organization role it grants.One of
admin,member,guest items[].workspaceAccess- Access it grants.One of
all,selected items[].workspaces- The workspaces it grants (for
all: the one it's stored in; every workspace is granted). items[].workspaces[].id- Workspace.
items[].workspaces[].name- Name.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit:feature: membersorfeature: guestsat Pro's 5 members or 10 guests (upgradeTo: business);feature: workspace_access, a member with selected workspaces on a plan without it. - 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/invitations" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b001e85f-94e6-410e-8489-71aa76631f7d" \
-H "Content-Type: application/json" \
-d '{
"email": "maya@brevanne.com",
"name": "Brevanne",
"role": "admin",
"workspaceAccess": "all",
"workspaceIds": [
"f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6"
]
}'Revoke an invitation
Organization owners and admins. Cancels it in every workspace it grants.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
invitation_id | string | Required | The invitation'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
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/invitations/44dd6197-d0a8-4cd3-bd03-3e59b3a51fa7" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a630cc50-880f-4fd7-9bcb-5f8ed25c31fe"Resend an invitation
Organization owners and admins. Sends a pending or expired invitation's email again; it expires 7 days from now. Resending is inviting again: an invitation whose role the caller couldn't give is 403, naming what's missing, and the caller answers for it from then on. A revoked or accepted invitation is 409. Rate limited: once per invitation every 5 minutes and 20 per organization an hour, else 429 with Retry-After.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
invitation_id | string | Required | The invitation'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
createdAt- Sent.
email- Invited address.
expiresAt- Expires (7 days).
id- Invitation ID.
name- Name.
role- The organization role it grants.One of
admin,member,guest workspaceAccess- Access it grants.One of
all,selected workspaces- The workspaces it grants (for
all: the one it's stored in; every workspace is granted). workspaces[].id- Workspace.
workspaces[].name- Name.
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/invitations/44dd6197-d0a8-4cd3-bd03-3e59b3a51fa7/resend" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f3c09ed7-aa42-467e-8e74-1dbefbcfa638"List an organization's people
Organization owners and admins. Members (paid seats) by name, then guests (free), with the workspaces each reaches, and pending invitations.
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
guests- Free guests.
invitations- Pending invitations, newest first.
invitations[].createdAt- Sent.
invitations[].email- Invited address.
invitations[].expiresAt- Expires (7 days).
invitations[].id- Invitation ID.
invitations[].name- Name.
invitations[].role- The organization role it grants.One of
admin,member,guest invitations[].workspaceAccess- Access it grants.One of
all,selected invitations[].workspaces- The workspaces it grants (for
all: the one it's stored in; every workspace is granted). invitations[].workspaces[].id- Workspace.
invitations[].workspaces[].name- Name.
items- People.
items[].addedAt- Joined.
items[].avatarUrl- Avatar.
items[].email- Email.
items[].name- Name.
items[].role- Organization role. Members (owner, admin, member) are paid seats; guests are free.One of
owner,admin,member,guest items[].seat- Takes a paid seat.
items[].status- Suspended people can't sign in to the organization's workspaces.One of
active,suspended items[].userId- Person.
items[].version- Version for
expectedVersion. items[].workspaceAccess- Every workspace (including later ones) or the selected ones.One of
all,selected items[].workspaces- The workspaces they reach, by name.
items[].workspaces[].id- Workspace.
items[].workspaces[].name- Name.
items[].workspaces[].role- Their role there.One of
owner,admin,member,guest members- Paid seats.
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
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/members" \
-H "Authorization: Bearer $PLUTO_KEY"Change a person's role or workspaces
Organization owners and admins (owners, signed in, for anything involving the owner role: no API key or agent grants or removes ownership; the last owner can't be demoted or suspended). role may also be billing or a custom organization role's ID, never beyond the caller's own access. Owners and admins reach every workspace; members every one or the selected ones (as member or admin in each); guests the selected ones, to review. Their workspace memberships follow. Making a guest a member takes a paid seat. Giving a member only the selected workspaces comes with Business and Enterprise.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
role- Organization role:
owner,admin,member,guest,billingor a custom organization role's ID (GET /access/roles). status- Suspend or reactivate everywhere in the organization.One of
active,suspended workspaceAccess- For members.One of
all,selected workspaces- The workspaces they reach with
selectedaccess (replaces the current ones), or per-workspace roles. workspaces[].id- Workspace.
workspaces[].role- For members: their role in this workspace.One of
member,admin
Response
addedAt- Joined.
avatarUrl- Avatar.
email- Email.
name- Name.
role- Organization role. Members (owner, admin, member) are paid seats; guests are free.One of
owner,admin,member,guest seat- Takes a paid seat.
status- Suspended people can't sign in to the organization's workspaces.One of
active,suspended userId- Person.
version- Version for
expectedVersion. workspaceAccess- Every workspace (including later ones) or the selected ones.One of
all,selected workspaces- The workspaces they reach, by name.
workspaces[].id- Workspace.
workspaces[].name- Name.
workspaces[].role- Their role there.One of
owner,admin,member,guest
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit:feature: workspace_access(upgradeTo: business), selected workspaces for a member on a plan without them;feature: membersorfeature: guests, Pro's 5 members or 10 guests. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/members/66edca53-0813-467f-bdb8-313e9ad9882f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7599fb1d-da23-4e53-9249-620f9677deea" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"role": "owner",
"status": "active",
"workspaceAccess": "all",
"workspaces": [
{
"id": "f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6",
"role": "member"
}
]
}'Remove a person, or leave
Removes them from the organization and every workspace in it (owners to remove an owner, signed in). A signed-in person can remove themselves to leave with any role, unless they're the last owner; an API key or agent never removes the person it acts for (403). Their work stays. The loops that ran as them are paused and, with their Agent chats, move to transferTo for review (the workspaces' admins are told). Their connected agents and Pluto MCP connections are revoked and the webhooks they set up are turned off. Their API keys and agent clients are revoked, or with credentials=hand_over_to_me each API key and service agent client is re-issued to you where you may hold it (you manage credentials in its workspace and hold its scopes there, from then on bounded by your role): a new secret shown once in this answer, an agent client also a new clientId, and the old one stops at once with what it made. The rest are revoked, each with why. Never for yourself (422), nor while the organization's credential policy keeps handing over off (403). Without credentials the answer is 204.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user's ID. |
transferTo | string | Optional | Who takes over their loops and chats: an active owner or admin of the organization, or you. Defaults to you; for someone leaving, to an owner. Required when an API key or agent removes someone who owns loops or chats (422). |
credentials | string | Optional | revoke (the default) or hand_over_to_me. Sent, the answer is 200 with handedOver and revoked. |
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
handedOver- Re-issued to you, each with its new secret in this answer only (an agent client with its new
clientIdtoo); empty unless you chosehand_over_to_me. handedOver[].allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. handedOver[].clientId- An agent client's new OAuth client ID; absent for an API key.
handedOver[].createdAt- Created.
handedOver[].createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. handedOver[].delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
handedOver[].detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp handedOver[].expiresAt- When it stops working by itself; null: never.
handedOver[].id- Credential ID.
handedOver[].kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp handedOver[].lastUsedAt- Last use.
handedOver[].lastUsedIp- The address of its last use.
handedOver[].name- Name.
handedOver[].notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. handedOver[].replaces- The credential it replaces, now revoked.
handedOver[].resources- What it reaches in the workspace.
handedOver[].resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.handedOver[].scopes- Scopes; never more than the person's current role.
handedOver[].secret- The new secret: in the first response only, never in a replay.
handedOver[].userEmail- Their email.
handedOver[].userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
handedOver[].userName- Their name.
handedOver[].workspaceId- The workspace it works in.
handedOver[].workspaceName- Its name.
revoked- Revoked with their access; when you chose
hand_over_to_me, each with why it wasn't handed over. revoked[].detail- Key kind, or client kind:
m2ma service,mcpan agent acting for them.One ofsecret,publishable,m2m,mcp revoked[].id- Credential ID.
revoked[].kind- What it is.One of
api_key,agent_client revoked[].messagereasonin one sentence.revoked[].name- Name.
revoked[].reason- Why it isn't handed over, when that was asked: it's their own agent (
own_agent), you don't manage credentials in its workspace (manage), it holds access you don't have there (scopes), your organization doesn't let you have agents (agents), it's the credential making the request (in_use), or it changed while they were being removed (changed). Null otherwise.One ofown_agent,manage,scopes,agents,in_use,changed revoked[].workspaceId- The workspace it works in.
revoked[].workspaceName- Its name.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/members/66edca53-0813-467f-bdb8-313e9ad9882f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b9c55bc2-2c9d-4d44-b465-5ac3d4990d76"Take over a person's API keys
Organization owners and admins, and someone who may manage everyone's credentials in some of its workspaces for those workspaces'. Before someone leaves, takes over the API keys and service (M2M) agent clients they're accountable for: nothing is transferred with a live secret, so each is re-issued to toUserId, which must be the caller's own person and may manage everyone's credentials in its workspace, with the same name, kind, scopes and expiry and a new secret returned once (an agent client also gets a new clientId). The old one is revoked at once, so the leaving person's copy stops working. Their own agents (connected agents and agent clients acting for them), credentials with scopes the new person can't hold there and the credential making the request aren't re-issued (skipped); they're revoked when the person leaves. An old credential is revoked with what it made, as any revoked credential is: what of that can be re-issued is, and the rest is revoked with it (revoked), its webhooks turned off. Refused while the organization's credential policy keeps handing over off (403).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user'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
toUserId- You: the person taking the keys over.
Response
items- Re-issued keys and agent clients, each with its new secret once.
items[].allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. items[].clientId- An agent client's new OAuth client ID; absent for an API key.
items[].createdAt- Created.
items[].createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. items[].delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
items[].detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp items[].expiresAt- When it stops working by itself; null: never.
items[].id- Credential ID.
items[].kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp items[].lastUsedAt- Last use.
items[].lastUsedIp- The address of its last use.
items[].name- Name.
items[].notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. items[].replaces- The credential it replaces, now revoked.
items[].resources- What it reaches in the workspace.
items[].resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.items[].scopes- Scopes; never more than the person's current role.
items[].secret- The new secret: in the first response only, never in a replay.
items[].userEmail- Their email.
items[].userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
items[].userName- Their name.
items[].workspaceId- The workspace it works in.
items[].workspaceName- Its name.
revoked- Made by a re-issued key and not re-issued themselves: revoked with it.
revoked[].allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. revoked[].createdAt- Created.
revoked[].createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. revoked[].delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
revoked[].detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp revoked[].expiresAt- When it stops working by itself; null: never.
revoked[].id- Credential ID.
revoked[].kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp revoked[].lastUsedAt- Last use.
revoked[].lastUsedIp- The address of its last use.
revoked[].name- Name.
revoked[].notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. revoked[].resources- What it reaches in the workspace.
revoked[].resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.revoked[].scopes- Scopes; never more than the person's current role.
revoked[].userEmail- Their email.
revoked[].userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
revoked[].userName- Their name.
revoked[].workspaceId- The workspace it works in.
revoked[].workspaceName- Its name.
skipped- Not re-issued.
skipped[].allowedIps- The addresses or ranges (
address/length) it works from (keys and agent clients); null: anywhere. skipped[].createdAt- Created.
skipped[].createdByActor- Who made it (
kind,id,name: a person, an API key or an agent); null for a person's own agent. skipped[].delivering- A webhook's: whether events go out to it now, only while the person accountable for it may manage webhooks in its workspace. Absent for every other kind.
skipped[].detail- Key kind, client kind or how the agent connected.One of
secret,publishable,m2m,mcp,connection,registration,webhook,pluto_mcp skipped[].expiresAt- When it stops working by itself; null: never.
skipped[].id- Credential ID.
skipped[].kind- What it is: a webhook or a Pluto MCP connection only in the organization's list.One of
api_key,agent_client,agent_connection,webhook,pluto_mcp skipped[].lastUsedAt- Last use.
skipped[].lastUsedIp- The address of its last use.
skipped[].name- Name.
skipped[].notDelivering- A webhook's: why it doesn't deliver now (
reason:role,no_access,credential_endedornobody;userId,userName,message). Absent while it delivers and for every other kind. skipped[].resources- What it reaches in the workspace.
skipped[].resources.adAccountsall: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.skipped[].scopes- Scopes; never more than the person's current role.
skipped[].userEmail- Their email.
skipped[].userId- The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
skipped[].userName- Their name.
skipped[].workspaceId- The workspace it works in.
skipped[].workspaceName- Its name.
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/members/66edca53-0813-467f-bdb8-313e9ad9882f/credentials/transfer" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 28af674c-e26c-41f6-b487-7ac16f063ece" \
-H "Content-Type: application/json" \
-d '{
"toUserId": "18449a30-42d1-4232-83b1-d0003af029a0"
}'Preview removing a person
Organization owners and admins, and the person themselves (before leaving). The loops they own (paused when they're suspended or removed; on removal they move, still paused, to whoever takes over), how many Agent chats they have (moved on removal), their API keys, agent clients, connected agents and Pluto MCP connections, which are revoked, and the webhooks they set up, which are turned off. handOver says whether you may take their API keys and service agent clients over when removing them (credentials=hand_over_to_me; never for yourself, nor while the organization's credential policy keeps it off), what that would re-issue to you and what it would revoke instead, each with why.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user'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
agentClients- Agent clients they made or that act for them.
agentClients[].id- Credential ID.
agentClients[].name- Name.
agentClients[].workspaceId- The workspace it works in.
agentClients[].workspaceName- Its name.
agentConnections- Agents they connected.
agentConnections[].id- Credential ID.
agentConnections[].name- Name.
agentConnections[].workspaceId- The workspace it works in.
agentConnections[].workspaceName- Its name.
apiKeys- API keys they made.
apiKeys[].id- Credential ID.
apiKeys[].name- Name.
apiKeys[].workspaceId- The workspace it works in.
apiKeys[].workspaceName- Its name.
chats- Their Agent chats in the organization.
handOverhandOver.available- You may remove them with
credentials=hand_over_to_me. handOver.handedOver- What would be re-issued to you.
handOver.handedOver[].detail- Key kind, or client kind:
m2ma service,mcpan agent acting for them.One ofsecret,publishable,m2m,mcp handOver.handedOver[].id- Credential ID.
handOver.handedOver[].kind- What it is.One of
api_key,agent_client handOver.handedOver[].messagereasonin one sentence.handOver.handedOver[].name- Name.
handOver.handedOver[].reason- Why it isn't handed over, when that was asked: it's their own agent (
own_agent), you don't manage credentials in its workspace (manage), it holds access you don't have there (scopes), your organization doesn't let you have agents (agents), it's the credential making the request (in_use), or it changed while they were being removed (changed). Null otherwise.One ofown_agent,manage,scopes,agents,in_use,changed handOver.handedOver[].workspaceId- The workspace it works in.
handOver.handedOver[].workspaceName- Its name.
handOver.messageunavailablein one sentence.handOver.revoked- What would be revoked instead, each with why.
handOver.revoked[].detail- Key kind, or client kind:
m2ma service,mcpan agent acting for them.One ofsecret,publishable,m2m,mcp handOver.revoked[].id- Credential ID.
handOver.revoked[].kind- What it is.One of
api_key,agent_client handOver.revoked[].messagereasonin one sentence.handOver.revoked[].name- Name.
handOver.revoked[].reason- Why it isn't handed over, when that was asked: it's their own agent (
own_agent), you don't manage credentials in its workspace (manage), it holds access you don't have there (scopes), your organization doesn't let you have agents (agents), it's the credential making the request (in_use), or it changed while they were being removed (changed). Null otherwise.One ofown_agent,manage,scopes,agents,in_use,changed handOver.revoked[].workspaceId- The workspace it works in.
handOver.revoked[].workspaceName- Its name.
handOver.unavailable- Why not: the organization's credential policy keeps handing over off (
policy), it's you leaving (yourself), or nobody is accountable for the credential asking (no_person). Null when it's available.One ofpolicy,yourself,no_person loops- Loops they own, archived ones aside.
loops[].id- Loop ID.
loops[].name- Name.
loops[].status- Status.One of
draft,active,paused loops[].workspaceId- Workspace.
loops[].workspaceName- Its name.
plutoMcp- Their Pluto MCP connections.
plutoMcp[].id- Credential ID.
plutoMcp[].name- Name.
plutoMcp[].workspaceId- The workspace it works in.
plutoMcp[].workspaceName- Its name.
webhooks- Webhooks they set up, or a credential of theirs did.
webhooks[].id- Webhook ID.
webhooks[].url- Its endpoint.
webhooks[].workspaceId- The workspace it works in.
webhooks[].workspaceName- Its name.
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/members/66edca53-0813-467f-bdb8-313e9ad9882f/offboarding" \
-H "Authorization: Bearer $PLUTO_KEY"Make an admin an owner
An owner of the organization, signed in to Pluto Ads: no API key or agent grants ownership (403). The person must be an active admin (409 otherwise). An organization can have several owners; with stepDown the caller becomes an admin. They're owners in every workspace.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user'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
stepDown- Become an admin yourself.
Response
addedAt- Joined.
avatarUrl- Avatar.
email- Email.
name- Name.
role- Organization role. Members (owner, admin, member) are paid seats; guests are free.One of
owner,admin,member,guest seat- Takes a paid seat.
status- Suspended people can't sign in to the organization's workspaces.One of
active,suspended userId- Person.
version- Version for
expectedVersion. workspaceAccess- Every workspace (including later ones) or the selected ones.One of
all,selected workspaces- The workspaces they reach, by name.
workspaces[].id- Workspace.
workspaces[].name- Name.
workspaces[].role- Their role there.One of
owner,admin,member,guest
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/members/66edca53-0813-467f-bdb8-313e9ad9882f/ownership" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: d64a7613-3528-4245-b4a0-f83b10d28959" \
-H "Content-Type: application/json" \
-d '{
"stepDown": true
}'Restore an organization
An owner, signed in to Pluto Ads: person only, so API keys, agents and MCP clients get 403 (there's no MCP tool for it). Brings back an organization scheduled for deletion, and the workspaces its deletion scheduled, as they were (an archived workspace comes back archived). Workspaces deleted on their own before stay scheduled. Loops stay paused until someone turns them back on; revoked credentials, removed guests and disconnected integrations aren't restored. The subscription stays set to end with the paid period until an owner resumes it in Billing.
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. |
Response
deletionRequestedAt- When it was scheduled for deletion.
id- Organization ID.
name- Name.
purgeAfter- When it's deleted for good (30 days after it was scheduled); restorable until then.
statusactive, ordeleting: scheduled for deletion, with every workspace in it; an owner can restore it untilpurgeAfter.One ofactive,deletingsubscriptionEndsAt- The end of the paid period, when the subscription is set to end then; null without a subscription.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not a member of this organization.
- 409It isn't scheduled for deletion, or deleting its data has already started (
reason: purge_started): then it can't be restored. - 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/restore" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 43e18f24-2e36-4710-a874-6b64be1da91e"