Connected agents
Agent clients, and the agents people connected by signing in.
List agent clients
The agent clients you're accountable for or that act for you, or everyone's with credentials:manage.
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[].actingUserId- The person an
mcpclient acts for. items[].allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. items[].clientId- OAuth client ID.
items[].clientSecret- Only in the create and rotate responses.
items[].createdAt- Created.
items[].createdBy- The person accountable: the creator, or the person an agent acts for.
items[].createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. items[].effectiveCapabilities- What it can do now, by capability ID: its scopes within its person's current role (the person an
mcpclient acts for, anm2mclient's maker) and what the organization's policy lets their agent clients hold; nothing once it expired. items[].expiresAt- When it stops working by itself; null: never.
items[].id- Agent client.
items[].kind- Kind.One of
mcp,m2m items[].name- Name.
items[].narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, when it does:role(its person's current role holds less, or they can't act in the workspace now),policy(the organization lets members' agent clients hold less, or members have no agents),expired, orresources(it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope. 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.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/agent-clients" \
-H "Authorization: Bearer $PLUTO_KEY"Register an agent client
Creates an OAuth client; exchange its credentials for an access token at the authorization server's token endpoint (client credentials). mcp clients act for the creating person. 403 while the organization lets only its owners and admins create agent clients (credentialPolicy.membersMayCreateAgentClients), and a scope beyond what it lets members' clients hold (membersAgentClientAccess) is 422 invalid, saying what it allows, with no missingCapability: the role allows it.
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
allowedIps- The addresses or ranges it works from, at most 20; a request from anywhere else is refused. Without it, or empty: anywhere.
expiresAt- When the client stops working by itself, within two years and within the organization's limit for members when it sets one. Without it the client lasts 90 days, or that limit when it's shorter;
null: it never expires, where no limit applies (otherwise422). kind- Kind.One of
mcp,m2m name- Name.
resources- The ad accounts it works in:
all, or chosen ones by ID, as list_platforms names them. Without it, the ones the caller reaches (a person every one); an ad account the caller doesn't reach, or that isn't the workspace's, is422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- Scopes; never more than the creator holds.
Response
actingUserId- The person an
mcpclient acts for. allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. clientId- OAuth client ID.
clientSecret- Only in the create and rotate responses.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- What it can do now, by capability ID: its scopes within its person's current role (the person an
mcpclient acts for, anm2mclient's maker) and what the organization's policy lets their agent clients hold; nothing once it expired. expiresAt- When it stops working by itself; null: never.
id- Agent client.
kind- Kind.One of
mcp,m2m name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, when it does:role(its person's current role holds less, or they can't act in the workspace now),policy(the organization lets members' agent clients hold less, or members have no agents),expired, orresources(it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope. 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.
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/agent-clients" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f49b0d1b-0bf5-4779-ad82-95797f291975" \
-H "Content-Type: application/json" \
-d '{
"allowedIps": [
"203.0.113.7"
],
"expiresAt": null,
"kind": "mcp",
"name": "Brevanne ops agent",
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Narrow an agent client
Gives the client less access: its client ID and secret stay, and from its tokens' next request it does only what scopes keeps. A scope it doesn't hold is 422: narrowing never adds access. What it made keeps its own access. Your own, or anyone's with credentials:manage (404 otherwise). A change is audited once, with the scopes before and after.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent client'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: scopes it holds now or fewer, each with what it requires beside it.
Response
actingUserId- The person an
mcpclient acts for. allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. clientId- OAuth client ID.
clientSecret- Only in the create and rotate responses.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- What it can do now, by capability ID: its scopes within its person's current role (the person an
mcpclient acts for, anm2mclient's maker) and what the organization's policy lets their agent clients hold; nothing once it expired. expiresAt- When it stops working by itself; null: never.
id- Agent client.
kind- Kind.One of
mcp,m2m name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, when it does:role(its person's current role holds less, or they can't act in the workspace now),policy(the organization lets members' agent clients hold less, or members have no agents),expired, orresources(it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope. 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.
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/agent-clients/7309b817-e2ed-415d-ae96-88e322c072d4" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 64b611cb-3a65-4f51-936c-d8345402935f" \
-H "Content-Type: application/json" \
-d '{
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Disconnect an agent client
Its tokens are refused from the next request. Your own, or anyone's with credentials:manage (404 otherwise). A client can't revoke itself (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent client'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/agent-clients/7309b817-e2ed-415d-ae96-88e322c072d4" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b59e6fd7-de74-4548-9210-595b5692ed36"Rotate an agent client's secret
Gives the client a new secret and keeps its clientId: the old secret and the access tokens it got stop working at once, so what uses it changes only the secret. The client isn't revoked, so what it made keeps working (rotating an API key differs: the old key is revoked, and what it made with it). The new secret is in clientSecret in this response only. Your own, or anyone's with credentials:manage (404 otherwise). A client can't rotate itself (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent client'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
actingUserId- The person an
mcpclient acts for. allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. clientId- OAuth client ID.
clientSecret- Only in the create and rotate responses.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- What it can do now, by capability ID: its scopes within its person's current role (the person an
mcpclient acts for, anm2mclient's maker) and what the organization's policy lets their agent clients hold; nothing once it expired. expiresAt- When it stops working by itself; null: never.
id- Agent client.
kind- Kind.One of
mcp,m2m name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, when it does:role(its person's current role holds less, or they can't act in the workspace now),policy(the organization lets members' agent clients hold less, or members have no agents),expired, orresources(it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope. 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.
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/agent-clients/7309b817-e2ed-415d-ae96-88e322c072d4/rotate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 629350cb-c02f-4bc9-bbba-0b767a3236a4"List connected agents
Agents people connected by signing in from their MCP client (Claude, Cursor, …). People see their own; admins see everyone's.
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[].clientId- OAuth client ID.
items[].clientName- The OAuth client's name; null until it connects.
items[].connectedAt- First use.
items[].createdAt- Consent time.
items[].id- Connection.
items[].lastUsedAt- Last use (to the minute).
items[].methodoauth: signed in from its MCP client.auth_md: registered itself through auth.md and was claimed by the person.One ofoauth,auth_mditems[].name- How activity names the agent: <client> via <person>.
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 beyond the person's role.
items[].status- Pending until the agent first uses its token.One of
pending,connected items[].userId- The person it acts for.
items[].userName- Their name.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/agent-connections" \
-H "Authorization: Bearer $PLUTO_KEY"Approve an agent connection
Called by the app's sign-in page for MCP clients with the external_auth_id the authorization server sent it. Choose the workspace with Pluto-Workspace. Completes the sign-in and returns redirectUri, where the browser continues.
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
externalAuthId- From the authorization server's redirect to the sign-in page.
resources- The ad accounts it works in:
all, or chosen ones by ID, as list_platforms names them. Without it, the ones the caller reaches (a person every one); an ad account the caller doesn't reach, or that isn't the workspace's, is422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- Scopes; never more than the creator holds.
Response
connectionconnection.clientId- OAuth client ID.
connection.clientName- The OAuth client's name; null until it connects.
connection.connectedAt- First use.
connection.createdAt- Consent time.
connection.id- Connection.
connection.lastUsedAt- Last use (to the minute).
connection.methodoauth: signed in from its MCP client.auth_md: registered itself through auth.md and was claimed by the person.One ofoauth,auth_mdconnection.name- How activity names the agent: <client> via <person>.
connection.resources- What it reaches in the workspace.
connection.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.connection.scopes- Scopes, never beyond the person's role.
connection.status- Pending until the agent first uses its token.One of
pending,connected connection.userId- The person it acts for.
connection.userName- Their name.
redirectUri- The authorization server's consent screen, then the agent.
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/agent-connections" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 221138d7-d979-4ea0-8d5e-c28cacb440aa" \
-H "Content-Type: application/json" \
-d '{
"externalAuthId": "42f0d252-e115-435f-8afb-beed0e7a5884",
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Claim an agent registered with auth.md
Called by the app's claim page for agents that registered through auth.md with the claim attempt token from the agent's verification link. Choose the workspace with Pluto-Workspace. Returns the connection and userCode, which the person reads back to the agent to finish the claim.
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
claimAttemptToken- The
tokenquery parameter of the verification link. resources- The ad accounts it works in:
all, or chosen ones by ID, as list_platforms names them. Without it, the ones the caller reaches (a person every one); an ad account the caller doesn't reach, or that isn't the workspace's, is422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- Scopes; never more than the creator holds.
Response
connectionconnection.clientId- OAuth client ID.
connection.clientName- The OAuth client's name; null until it connects.
connection.connectedAt- First use.
connection.createdAt- Consent time.
connection.id- Connection.
connection.lastUsedAt- Last use (to the minute).
connection.methodoauth: signed in from its MCP client.auth_md: registered itself through auth.md and was claimed by the person.One ofoauth,auth_mdconnection.name- How activity names the agent: <client> via <person>.
connection.resources- What it reaches in the workspace.
connection.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.connection.scopes- Scopes, never beyond the person's role.
connection.status- Pending until the agent first uses its token.One of
pending,connected connection.userId- The person it acts for.
connection.userName- Their name.
userCode- Read back to the agent; works once and expires in minutes.
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/agent-connections/claims" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 55689473-103c-4290-af82-9f1e138750ad" \
-H "Content-Type: application/json" \
-d '{
"claimAttemptToken": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Narrow a connected agent
Gives a connected agent less access without reconnecting it: from its tokens' next request it does only what scopes keeps. A scope it doesn't hold is 422: narrowing never adds access. Anyone who can read the workspace narrows their own connected agents (404 for someone else's); whoever may manage everyone's credentials narrows anyone's. A change is audited once, with the scopes before and after.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent connection'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: scopes it holds now or fewer, each with what it requires beside it.
Response
clientId- OAuth client ID.
clientName- The OAuth client's name; null until it connects.
connectedAt- First use.
createdAt- Consent time.
id- Connection.
lastUsedAt- Last use (to the minute).
methodoauth: signed in from its MCP client.auth_md: registered itself through auth.md and was claimed by the person.One ofoauth,auth_mdname- How activity names the agent: <client> via <person>.
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 beyond the person's role.
status- Pending until the agent first uses its token.One of
pending,connected userId- The person it acts for.
userName- Their 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/agent-connections/1b11781e-ffcb-436c-98e4-0b9ec6796ae0" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e85ebf3b-7b69-4a9d-8213-a974316e7585" \
-H "Content-Type: application/json" \
-d '{
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Disconnect a connected agent
Its tokens are refused from the next request, and the API keys and agent clients it created are revoked with it and its webhooks turned off. Anyone who can read the workspace disconnects their own connected agents (404 for someone else's); admins disconnect anyone's. API keys and M2M clients have no person, so without admin they get 403. A connection can't disconnect itself (409).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent connection'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/agent-connections/1b11781e-ffcb-436c-98e4-0b9ec6796ae0" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 27529dc8-5da8-442b-ab3c-c34a8ae2387d"List your connected agents
Your API keys and agents.
The signed-in person's own credentials in every workspace they're active in: their connected agents (sign-ins from Claude, Cursor or other MCP clients, claimed agent registrations, and agent clients acting for them), the API keys they're accountable for and the service agent clients they own, each with its scopes, when and from where it was last used, when it was created and when it expires. Account settings. Guests can't connect agents: 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Your API keys and agents.
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.
curl "$PLUTO_API/me/agents" \
-b "plutoads_session=$PLUTO_SESSION"Narrow one of your agents
Gives one of the signed-in person's own agents, in any workspace, less access without reconnecting it: from its next request it does only what scopes keeps, scopes it holds now or fewer. A scope it doesn't hold is 422: narrowing never adds access. Guests can't connect agents: 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent'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/me/agents/8558d35e-8143-44d2-ac4e-c3ccd5ce664f" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 2361bc94-6b4d-475b-84ce-6b0a2492a6e2" \
-H "Content-Type: application/json" \
-d '{
"resources": {
"adAccounts": "all"
},
"scopes": [
"read"
]
}'Revoke one of your API keys or agents
Disconnects one of the signed-in person's own agents, or revokes an API key or service agent client they're accountable for, in any workspace: its next request is refused, and what it made ends with it. Guests can't connect agents: 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The agent'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/me/agents/8558d35e-8143-44d2-ac4e-c3ccd5ce664f" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 73401538-3a56-4128-bd03-1f6ae5263fb1"