Members
A workspace's members and invitations.
List members
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
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- This page.
items[].accessRole- The narrower role a member holds; null for a tier's own role (a member without one is a Manager).
items[].accessRole.id- A built-in role's key (
media_buyer, …) or a custom role's ID. items[].accessRole.name- Its name.
items[].addedAt- Joined.
items[].assignedCount- Ads assigned in unarchived launches.
items[].avatarUrl- Avatar.
items[].email- Email; omitted when a guest lists the members.
items[].name- Name.
items[].role- Membership tier (seats follow it).One of
owner,admin,member,guest items[].seat- A paid seat of the organization (any role but guest in one of its workspaces). Making a guest a member or admin adds one; making someone a guest everywhere frees it.
items[].status- Status.One of
active,suspended items[].userId- Person.
items[].version- Version.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/members" \
-H "Authorization: Bearer $PLUTO_KEY"List invitations
Empty for guests: invitations name people by email.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Optional | pending (default) or all. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size. |
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- This page.
items[].accessRole- The narrower role it grants (
id: a built-in role's key or a custom role's ID;name); null for a tier's own role. items[].createdAt- Sent.
items[].email- Email.
items[].expiresAt- Expiry.
items[].id- Invitation.
items[].invitedBy- Who invited, or sent it again last: a person, or the person behind the API key or agent that did.
items[].invitedByName- Their name.
items[].name- Name.
items[].role- Membership tier it grants.One of
owner,admin,member,guest items[].status- Status; a pending invitation past
expiresAtreads as expired.One ofpending,accepted,revoked,expired nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/members/invitations" \
-H "Authorization: Bearer $PLUTO_KEY"Invite someone by email
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
email- Email.
name- Name.
role- Role on joining: a tier (
owner,admin,member,guest), a built-in role (manager, the same asmember;media_buyer,creative,analyst) or a custom workspace role's ID, never beyond the caller's own access. A guest reads, comments and approves or requests changes; guests are free.
Response
accessRole- The narrower role it grants (
id: a built-in role's key or a custom role's ID;name); null for a tier's own role. createdAt- Sent.
email- Email.
expiresAt- Expiry.
id- Invitation.
invitedBy- Who invited, or sent it again last: a person, or the person behind the API key or agent that did.
invitedByName- Their name.
name- Name.
role- Membership tier it grants.One of
owner,admin,member,guest status- Status; a pending invitation past
expiresAtreads as expired.One ofpending,accepted,revoked,expired
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/members/invitations" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8fb769d8-3f53-406d-a55b-dab17c78323f" \
-H "Content-Type: application/json" \
-d '{
"email": "maya@brevanne.com",
"name": "Maya Patel",
"role": "owner"
}'Revoke an invitation
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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
accessRole- The narrower role it grants (
id: a built-in role's key or a custom role's ID;name); null for a tier's own role. createdAt- Sent.
email- Email.
expiresAt- Expiry.
id- Invitation.
invitedBy- Who invited, or sent it again last: a person, or the person behind the API key or agent that did.
invitedByName- Their name.
name- Name.
role- Membership tier it grants.One of
owner,admin,member,guest status- Status; a pending invitation past
expiresAtreads as expired.One ofpending,accepted,revoked,expired
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/members/invitations/44dd6197-d0a8-4cd3-bd03-3e59b3a51fa7/revoke" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f91460e4-e72e-4612-aa3a-5bfcbb6e5a8a"Change a member's role
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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- New role: a tier (
owner,admin,member,guest), a built-in role (manager, the same asmember;media_buyer,creative,analyst) or a custom workspace role's ID (GET /access/roles). A guest reads, comments and approves or requests changes; guests are free. Never beyond the caller's own access:403names the missing capability.
Response
accessRole- The narrower role a member holds; null for a tier's own role (a member without one is a Manager).
accessRole.id- A built-in role's key (
media_buyer, …) or a custom role's ID. accessRole.name- Its name.
addedAt- Joined.
assignedCount- Ads assigned in unarchived launches.
avatarUrl- Avatar.
email- Email; omitted when a guest lists the members.
name- Name.
role- Membership tier (seats follow it).One of
owner,admin,member,guest seat- A paid seat of the organization (any role but guest in one of its workspaces). Making a guest a member or admin adds one; making someone a guest everywhere frees it.
status- Status.One of
active,suspended userId- Person.
version- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 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/members/66edca53-0813-467f-bdb8-313e9ad9882f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d4cffbe4-3820-486c-9cad-a8d960ad2c2f" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"role": "owner"
}'Remove a member, or leave the workspace
Removing someone else needs admin (an owner to remove an owner). Anyone can remove themselves to leave the workspace, unless they are its last owner. Their past work, comments and assignments stay. Their connected agents and Pluto MCP connections here are revoked and the webhooks they set up here are turned off. Their API keys and agent clients here are revoked, or with credentials=hand_over_to_me each API key and service agent client here is re-issued to you where you may hold it (you manage credentials here and hold its scopes): 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 |
|---|---|---|---|
user_id | string | Required | The user's ID. |
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/members/66edca53-0813-467f-bdb8-313e9ad9882f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a24e626c-e30d-4228-b8f1-79b8954384ae"Preview removing a member
Whoever may remove people from the workspace, and the person themselves before leaving it. What they own here, as the organization's preview says it for the whole organization: their loops, Agent chats, API keys, agent clients, connected agents, Pluto MCP connections and webhooks in this workspace, and handOver: whether you may remove them with credentials=hand_over_to_me, what that would re-issue to you and what it would revoke instead, each with why.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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/members/66edca53-0813-467f-bdb8-313e9ad9882f/offboarding" \
-H "Authorization: Bearer $PLUTO_KEY"Reactivate a member
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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. |
Response
accessRole- The narrower role a member holds; null for a tier's own role (a member without one is a Manager).
accessRole.id- A built-in role's key (
media_buyer, …) or a custom role's ID. accessRole.name- Its name.
addedAt- Joined.
assignedCount- Ads assigned in unarchived launches.
avatarUrl- Avatar.
email- Email; omitted when a guest lists the members.
name- Name.
role- Membership tier (seats follow it).One of
owner,admin,member,guest seat- A paid seat of the organization (any role but guest in one of its workspaces). Making a guest a member or admin adds one; making someone a guest everywhere frees it.
status- Status.One of
active,suspended userId- Person.
version- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 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/members/66edca53-0813-467f-bdb8-313e9ad9882f/reactivate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ce23663d-c0a5-4e92-a87d-ca592aa1dec1"Suspend a member (and their agents)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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. |
Response
accessRole- The narrower role a member holds; null for a tier's own role (a member without one is a Manager).
accessRole.id- A built-in role's key (
media_buyer, …) or a custom role's ID. accessRole.name- Its name.
addedAt- Joined.
assignedCount- Ads assigned in unarchived launches.
avatarUrl- Avatar.
email- Email; omitted when a guest lists the members.
name- Name.
role- Membership tier (seats follow it).One of
owner,admin,member,guest seat- A paid seat of the organization (any role but guest in one of its workspaces). Making a guest a member or admin adds one; making someone a guest everywhere frees it.
status- Status.One of
active,suspended userId- Person.
version- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 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/members/66edca53-0813-467f-bdb8-313e9ad9882f/suspend" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 18c47d15-933b-4e0e-a334-8b6231c382e7"