API reference

Connected agents

Agent clients, and the agents people connected by signing in.

GET/agent-clients

List agent clients

The agent clients you're accountable for or that act for you, or everyone's with credentials:manage.

Permission: admin

Parameters

NameTypeRequiredDescription
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actingUserIdstring (uuid) or null
The person an mcp client acts for.
items[].allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
items[].clientIdstringRequired
OAuth client ID.
items[].clientSecretstring or null
Only in the create and rotate responses.
items[].createdAtstring (date-time)Required
Created.
items[].createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
items[].createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
items[].effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role (the person an mcp client acts for, an m2m client's maker) and what the organization's policy lets their agent clients hold; nothing once it expired.
items[].expiresAtstring (date-time) or null
When it stops working by itself; null: never.
items[].idstring (uuid)Required
Agent client.
items[].kindstringRequired
Kind.One of mcp, m2m
items[].namestringRequired
Name.
items[].narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, 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, or resources (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[].resourcesobject
What it reaches in the workspace.
items[].resources.adAccountsstring or array of objectsRequired
all: 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[].scopesarray of stringsRequired
Scopes.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent-clients" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent-clients

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.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

allowedIpsarray of strings
The addresses or ranges it works from, at most 20; a request from anywhere else is refused. Without it, or empty: anywhere.
expiresAtstring (date-time) or null
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 (otherwise 422).
kindstringRequired
Kind.One of mcp, m2m
namestringRequired
Name.
resourcesobject
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, is 422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of strings
Scopes; never more than the creator holds.

Response201 Created

actingUserIdstring (uuid) or null
The person an mcp client acts for.
allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
clientIdstringRequired
OAuth client ID.
clientSecretstring or null
Only in the create and rotate responses.
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role (the person an mcp client acts for, an m2m client's maker) and what the organization's policy lets their agent clients hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Agent client.
kindstringRequired
Kind.One of mcp, m2m
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, 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, or resources (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.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: 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.
scopesarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    ]
  }'
PATCH/agent-clients/{id}

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.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent client's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

resourcesobject
The ad accounts it keeps, each one it reaches now (all only while it reaches every one); a wider set is 422. Without it, it keeps what it reaches.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of stringsRequired
What it keeps: scopes it holds now or fewer, each with what it requires beside it.

Response200 OK

actingUserIdstring (uuid) or null
The person an mcp client acts for.
allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
clientIdstringRequired
OAuth client ID.
clientSecretstring or null
Only in the create and rotate responses.
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role (the person an mcp client acts for, an m2m client's maker) and what the organization's policy lets their agent clients hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Agent client.
kindstringRequired
Kind.One of mcp, m2m
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, 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, or resources (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.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: 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.
scopesarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
    ]
  }'
DELETE/agent-clients/{id}

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

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent client's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent-clients/7309b817-e2ed-415d-ae96-88e322c072d4" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: b59e6fd7-de74-4548-9210-595b5692ed36"
POST/agent-clients/{id}/rotate

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

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent client's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actingUserIdstring (uuid) or null
The person an mcp client acts for.
allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
clientIdstringRequired
OAuth client ID.
clientSecretstring or null
Only in the create and rotate responses.
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role (the person an mcp client acts for, an m2m client's maker) and what the organization's policy lets their agent clients hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Agent client.
kindstringRequired
Kind.One of mcp, m2m
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, 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, or resources (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.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: 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.
scopesarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent-clients/7309b817-e2ed-415d-ae96-88e322c072d4/rotate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 629350cb-c02f-4bc9-bbba-0b767a3236a4"
GET/agent-connections

List connected agents

Agents people connected by signing in from their MCP client (Claude, Cursor, …). People see their own; admins see everyone's.

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].clientIdstring or null
OAuth client ID.
items[].clientNamestring or null
The OAuth client's name; null until it connects.
items[].connectedAtstring or null
First use.
items[].createdAtstring
Consent time.
items[].idstring (uuid)Required
Connection.
items[].lastUsedAtstring or null
Last use (to the minute).
items[].methodstringRequired
oauth: signed in from its MCP client. auth_md: registered itself through auth.md and was claimed by the person.One of oauth, auth_md
items[].namestringRequired
How activity names the agent: <client> via <person>.
items[].resourcesobject
What it reaches in the workspace.
items[].resources.adAccountsstring or array of objectsRequired
all: 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[].scopesarray of stringsRequired
Scopes, never beyond the person's role.
items[].statusstringRequired
Pending until the agent first uses its token.One of pending, connected
items[].userIdstring (uuid)Required
The person it acts for.
items[].userNamestring
Their name.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent-connections" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent-connections

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

externalAuthIdstringRequired
From the authorization server's redirect to the sign-in page.
resourcesobject
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, is 422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of strings
Scopes; never more than the creator holds.

Response201 Created

connectionobjectRequired
connection.clientIdstring or null
OAuth client ID.
connection.clientNamestring or null
The OAuth client's name; null until it connects.
connection.connectedAtstring or null
First use.
connection.createdAtstring
Consent time.
connection.idstring (uuid)Required
Connection.
connection.lastUsedAtstring or null
Last use (to the minute).
connection.methodstringRequired
oauth: signed in from its MCP client. auth_md: registered itself through auth.md and was claimed by the person.One of oauth, auth_md
connection.namestringRequired
How activity names the agent: <client> via <person>.
connection.resourcesobject
What it reaches in the workspace.
connection.resources.adAccountsstring or array of objectsRequired
all: 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.scopesarray of stringsRequired
Scopes, never beyond the person's role.
connection.statusstringRequired
Pending until the agent first uses its token.One of pending, connected
connection.userIdstring (uuid)Required
The person it acts for.
connection.userNamestring
Their name.
redirectUristringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    ]
  }'
POST/agent-connections/claims

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

claimAttemptTokenstringRequired
The token query parameter of the verification link.
resourcesobject
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, is 422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of strings
Scopes; never more than the creator holds.

Response201 Created

connectionobjectRequired
connection.clientIdstring or null
OAuth client ID.
connection.clientNamestring or null
The OAuth client's name; null until it connects.
connection.connectedAtstring or null
First use.
connection.createdAtstring
Consent time.
connection.idstring (uuid)Required
Connection.
connection.lastUsedAtstring or null
Last use (to the minute).
connection.methodstringRequired
oauth: signed in from its MCP client. auth_md: registered itself through auth.md and was claimed by the person.One of oauth, auth_md
connection.namestringRequired
How activity names the agent: <client> via <person>.
connection.resourcesobject
What it reaches in the workspace.
connection.resources.adAccountsstring or array of objectsRequired
all: 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.scopesarray of stringsRequired
Scopes, never beyond the person's role.
connection.statusstringRequired
Pending until the agent first uses its token.One of pending, connected
connection.userIdstring (uuid)Required
The person it acts for.
connection.userNamestring
Their name.
userCodestringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    ]
  }'
PATCH/agent-connections/{id}

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.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent connection's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

resourcesobject
The ad accounts it keeps, each one it reaches now (all only while it reaches every one); a wider set is 422. Without it, it keeps what it reaches.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of stringsRequired
What it keeps: scopes it holds now or fewer, each with what it requires beside it.

Response200 OK

clientIdstring or null
OAuth client ID.
clientNamestring or null
The OAuth client's name; null until it connects.
connectedAtstring or null
First use.
createdAtstring
Consent time.
idstring (uuid)Required
Connection.
lastUsedAtstring or null
Last use (to the minute).
methodstringRequired
oauth: signed in from its MCP client. auth_md: registered itself through auth.md and was claimed by the person.One of oauth, auth_md
namestringRequired
How activity names the agent: <client> via <person>.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: 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.
scopesarray of stringsRequired
Scopes, never beyond the person's role.
statusstringRequired
Pending until the agent first uses its token.One of pending, connected
userIdstring (uuid)Required
The person it acts for.
userNamestring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
    ]
  }'
DELETE/agent-connections/{id}

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

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent connection's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent-connections/1b11781e-ffcb-436c-98e4-0b9ec6796ae0" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 27529dc8-5da8-442b-ab3c-c34a8ae2387d"
GET/me/agents

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.

Permission: readApp session only

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Your API keys and agents.
items[].allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from (keys and agent clients); null: anywhere.
items[].createdAtstring (date-time)Required
Created.
items[].createdByActorobject or null
Who made it (kind, id, name: a person, an API key or an agent); null for a person's own agent.
items[].deliveringboolean
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[].detailstringRequired
Key kind, client kind or how the agent connected.One of secret, publishable, m2m, mcp, connection, registration, webhook, pluto_mcp
items[].expiresAtstring (date-time) or null
When it stops working by itself; null: never.
items[].idstring (uuid)Required
Credential ID.
items[].kindstringRequired
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[].lastUsedAtstring (date-time) or null
Last use.
items[].lastUsedIpstring or null
The address of its last use.
items[].namestringRequired
Name.
items[].notDeliveringobject
A webhook's: why it doesn't deliver now (reason: role, no_access, credential_ended or nobody; userId, userName, message). Absent while it delivers and for every other kind.
items[].resourcesobject
What it reaches in the workspace.
items[].resources.adAccountsstring or array of objectsRequired
all: 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[].scopesarray of stringsRequired
Scopes; never more than the person's current role.
items[].userEmailstring or null
Their email.
items[].userIdstring (uuid) or null
The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
items[].userNamestring or null
Their name.
items[].workspaceIdstring (uuid)Required
The workspace it works in.
items[].workspaceNamestringRequired
Its name.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/me/agents" \
  -b "plutoads_session=$PLUTO_SESSION"
PATCH/me/agents/{id}

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.

Permission: readApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

resourcesobject
The ad accounts it keeps, each one it reaches now (all only while it reaches every one); a wider set is 422. Without it, it keeps what it reaches.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of stringsRequired
What it keeps.

Response200 OK

allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from (keys and agent clients); null: anywhere.
createdAtstring (date-time)Required
Created.
createdByActorobject or null
Who made it (kind, id, name: a person, an API key or an agent); null for a person's own agent.
deliveringboolean
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.
detailstringRequired
Key kind, client kind or how the agent connected.One of secret, publishable, m2m, mcp, connection, registration, webhook, pluto_mcp
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Credential ID.
kindstringRequired
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
lastUsedAtstring (date-time) or null
Last use.
lastUsedIpstring or null
The address of its last use.
namestringRequired
Name.
notDeliveringobject
A webhook's: why it doesn't deliver now (reason: role, no_access, credential_ended or nobody; userId, userName, message). Absent while it delivers and for every other kind.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: 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.
scopesarray of stringsRequired
Scopes; never more than the person's current role.
userEmailstring or null
Their email.
userIdstring (uuid) or null
The person it acts for (a key's or M2M client's owner, the person accountable for a webhook).
userNamestring or null
Their name.
workspaceIdstring (uuid)Required
The workspace it works in.
workspaceNamestringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
    ]
  }'
DELETE/me/agents/{id}

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.

Permission: readApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe agent's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/me/agents/8558d35e-8143-44d2-ac4e-c3ccd5ce664f" \
  -b "plutoads_session=$PLUTO_SESSION" \
  -H "Idempotency-Key: 73401538-3a56-4128-bd03-1f6ae5263fb1"