API reference

Account

The signed-in person, their account and signing out.

GET/account

Get your account

Person only: every signed-in person, guests included, for their own account; never an API key, agent or MCP client (they get 403; there's no MCP tool for it). Your profile, your organizations, the ones where you're the only owner (deleting your account waits for those), the ones scheduled for deletion, and the ones you were removed from.

Any signed-in person, in the appGuests too

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

deletingOrganizationsarray of objectsRequired
Your organizations scheduled for deletion.
deletingOrganizations[].canRestorebooleanRequired
You're an owner and deleting hasn't started, so you can restore it.
deletingOrganizations[].idstring (uuid)Required
Organization ID.
deletingOrganizations[].namestringRequired
Name.
deletingOrganizations[].purgeAfterstring (date-time)Required
When it's deleted for good.
deletingOrganizations[].purgeStartedbooleanRequired
Deleting its data has started, so it can't be restored any more.
emailstringRequired
Your email address.
idstring (uuid)Required
Your person ID.
localestring or nullRequired
Your language in the app, on every device: en, da, de, sv, nb, es, fr, zh-Hans or ar; null for Automatic (your browser's language). A language that isn't available yet is kept and read as Automatic until it is.One of en, da, de, sv, nb, es, fr, zh-Hans, ar
namestringRequired
Your name.
organizationsarray of objectsRequired
Every organization you belong to, by name.
organizations[].idstring (uuid)Required
Organization ID.
organizations[].memberStatusstringRequired
Yours there.One of active, suspended
organizations[].namestringRequired
Name.
organizations[].rolestringRequired
Your role there.One of owner, admin, member, guest
organizations[].statusstringRequired
The organization's: deleting while scheduled for deletion.One of active, deleting
removedFromarray of objectsRequired
Organizations you were removed from and haven't rejoined, most recent first.
removedFrom[].atstring (date-time)Required
When you were removed.
removedFrom[].organizationIdstring (uuid)Required
Organization ID.
removedFrom[].organizationNamestringRequired
Its name.
soleOwnerOfarray of objectsRequired
Active organizations where you're the only active owner. Deleting your account waits until someone else owns each (or you delete it).
soleOwnerOf[].idstring (uuid)Required
Organization ID.
soleOwnerOf[].namestringRequired
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/account" \
  -b "plutoads_session=$PLUTO_SESSION"
PATCH/account

Change your name or language

Person only: every signed-in person, guests included, for their own account; never an API key, agent or MCP client (they get 403; there's no MCP tool for it). Send name, locale or both. name: your name as everyone in your workspaces sees it: members, comments, activity and who made what. Spaces around it are trimmed; 1 to 100 characters, no line breaks or other control characters. From then on it's yours: signing in again never replaces it with the name from Google, Microsoft or your sign-in provider. locale: the language the app uses for you on every device, or null for Automatic (also settable with the MCP tool set_preference, key locale). Answers your account, as GET /account.

Any signed-in person, in the appGuests too

Parameters

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

Request body

localestring or null
Your language in the app, on every device: en, da, de, sv, nb, es, fr, zh-Hans or ar; null for Automatic (your browser's language). A language that isn't available yet is kept and read as Automatic until it is.One of en, da, de, sv, nb, es, fr, zh-Hans, ar
namestring
Your full name, 1 to 100 characters.

Response200 OK

deletingOrganizationsarray of objectsRequired
Your organizations scheduled for deletion.
deletingOrganizations[].canRestorebooleanRequired
You're an owner and deleting hasn't started, so you can restore it.
deletingOrganizations[].idstring (uuid)Required
Organization ID.
deletingOrganizations[].namestringRequired
Name.
deletingOrganizations[].purgeAfterstring (date-time)Required
When it's deleted for good.
deletingOrganizations[].purgeStartedbooleanRequired
Deleting its data has started, so it can't be restored any more.
emailstringRequired
Your email address.
idstring (uuid)Required
Your person ID.
localestring or nullRequired
Your language in the app, on every device: en, da, de, sv, nb, es, fr, zh-Hans or ar; null for Automatic (your browser's language). A language that isn't available yet is kept and read as Automatic until it is.One of en, da, de, sv, nb, es, fr, zh-Hans, ar
namestringRequired
Your name.
organizationsarray of objectsRequired
Every organization you belong to, by name.
organizations[].idstring (uuid)Required
Organization ID.
organizations[].memberStatusstringRequired
Yours there.One of active, suspended
organizations[].namestringRequired
Name.
organizations[].rolestringRequired
Your role there.One of owner, admin, member, guest
organizations[].statusstringRequired
The organization's: deleting while scheduled for deletion.One of active, deleting
removedFromarray of objectsRequired
Organizations you were removed from and haven't rejoined, most recent first.
removedFrom[].atstring (date-time)Required
When you were removed.
removedFrom[].organizationIdstring (uuid)Required
Organization ID.
removedFrom[].organizationNamestringRequired
Its name.
soleOwnerOfarray of objectsRequired
Active organizations where you're the only active owner. Deleting your account waits until someone else owns each (or you delete it).
soleOwnerOf[].idstring (uuid)Required
Organization ID.
soleOwnerOf[].namestringRequired
Name.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 422Neither name nor locale was sent; name is empty, longer than 100 characters or has a control character; or locale isn't one of the app's languages.
  • 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/account" \
  -b "plutoads_session=$PLUTO_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en",
    "name": "Brevanne US"
  }'
POST/account/delete

Delete your account

Person only: every signed-in person, guests included, for their own account; never an API key, agent or MCP client (they get 403; there's no MCP tool for it). Type your email address in confirmEmail. Refused (409, reason: sole_owner, organizations) while you're the only active owner of an active organization: make someone else an owner first, or delete the organization. Otherwise immediate and final: you leave every organization (your loops and loop chats move to an owner, or else an admin, paused for review), every API key, agent and session of yours ends, your preferences, notification settings, Agent guidance and skills, inbox, follows and Agent chats that aren't a loop's are deleted, and your name on the work you leave behind reads "Deleted user". Signs you out. Signing in with the same email later starts a new, empty account.

Any signed-in person, in the appGuests too

Parameters

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

Request body

confirmEmailstringRequired
Your email address.

Response204 No Content

Done; no content.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409You're the only owner of an organization (reason: sole_owner, organizations).
  • 422confirmEmail doesn't match your email address.
  • 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.
  • 503Sign-in is unavailable; nothing was deleted.
curl -X POST "$PLUTO_API/account/delete" \
  -b "plutoads_session=$PLUTO_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmEmail": "maya@brevanne.com"
  }'
GET/account/export

Download a copy of your data

Person only: every signed-in person, guests included, for their own account; never an API key, agent or MCP client (they get 403; there's no MCP tool for it). A JSON file (Content-Disposition: attachment) with everything Pluto Ads holds about you: profile, organizations and workspace memberships, preferences and notification settings, follows, comments, reactions, your Agent chats with their messages, your activity, sessions and the credentials you made. Never secrets, tokens or their hashes.

Any signed-in person, in the appGuests too

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

activityarray of objects
What you did: the audit entries you made.
agentChatsarray of objects
Your Agent chats, each with its messages.
agentClientsarray of objects
Agent clients you created or that act for you. Never secrets.
agentGuidancearray of objects
Your Agent guidance per workspace.
agentSkillsarray of objects
Your Agent skills per workspace, with their prompts.
apiKeysarray of objects
API keys you created: name, kind, scopes, dates. Never secrets.
commentsarray of objects
Comments you wrote: workspace, launch, ad, text, dates.
connectedAgentsarray of objects
Agents you connected (MCP sign-ins, claimed registrations).
exportedAtstring (date-time)Required
When this copy was made.
followedAdsarray of objects
Ads you follow or stopped following.
followedThreadsarray of objects
Comment threads you follow or stopped following.
notificationSettingsarray of objects
Your notification settings per workspace.
organizationsarray of objects
Your organization memberships: role, status, workspace access.
preferencesarray of objects
Your view preferences per workspace.
profileobjectRequired
id, name, email, avatarUrl, createdAt.
reactionsarray of objects
Your reactions to comments.
sessionsarray of objects
Your sign-ins: created, last seen, expiry, ended. Never tokens.
truncatedarray of stringsRequired
Sections cut at 10,000 rows (the most recent kept).
workspacesarray of objects
Your workspace memberships: role and status.

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/account/export" \
  -b "plutoads_session=$PLUTO_SESSION"
GET/me

Get the signed-in person

The signed-in person and their workspaces.

Guests (review only) reach it too. workspace is the one the session has open; sent with Pluto-Workspace: <slug> (a Workspace URL instead of an ID), it is the one that slug names, whatever the session has open. block is null when that workspace opens; for a member who can't open it now it says why, as GET /workspace does in its problem: kind (workspace_deleted, organization_deleted, member_suspended or member_removed) with that problem's fields (workspaceId, organizationId, purgeAfter, or organizationId, organizationName), and workspace is null. With include=bootstrap the answer also carries bootstrap: asOf and reads, the app shell's first reads keyed by their path (/v1/organizations, /v1/organizations/{id}/workspaces, /v1/organizations/{id}/workspaces/{workspaceId}, /v1/organizations/{id}/billing, /v1/organizations/{id}/usage?period=current, /v1/integrations/meta/attention), each the exact body of that route for this person; a read the person may not make is left out, and without a workspace that opens there is no bootstrap.

Permission: readApp session onlyGuests too

Parameters

NameTypeRequiredDescription
includequerystringOptionalbootstrap adds the app shell's first reads.
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

user, workspace, workspaces[] (each with slug (its Workspace URL, the app's /<slug>/…), role, permissions (the scopes whose whole set they hold there), capabilities (what they may do there, by capability ID; an archived workspace lists reading only), organizationId (its organization) and organizationRole: the person's role in its organization, null without one; archived workspaces and ones scheduled for deletion aren't listed), organizations[]: every organization the person belongs to that isn't scheduled for deletion, each with id, role (theirs there) and capabilities (what their organization role allows there, by capability ID, such as billing:read, whatever the state of the workspace they're in), and releasedWorkspace: the workspace this session was taken out of because it was scheduled for deletion (id, name, status, purgeAfter, organizationId, canRestore), or null, heldInvitations[]: the invitations to the person's address that signing in didn't take because whoever sent them can no longer give what they give, until someone who can sends them again (id, and place: the workspace's name, or the organization's for an invitation to the organization), and features: the optional parts of the product this deployment offers, by name (true when on; the app hides what's off), platforms: the ad platforms the current workspace can use, Meta first, and capabilities: what this deployment can do on each of them, by platform, as GET /platforms serves it, and block.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace. With a slug in Pluto-Workspace, code is no_access: the person never had access to the workspace it names, or nobody has it (the two read the same).
  • 409code is workspace_moved: the slug is an earlier Workspace URL of a workspace the person belongs to; slug is its current one.
  • 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" \
  -b "plutoads_session=$PLUTO_SESSION"