API reference

Preferences

Your view preferences.

GET/preferences

Get your view preferences

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: readGuests 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

preferences by key.

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/preferences" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/preferences/{key}

Save a view preference

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can. key is creativeView, boardDisplay, tableDisplay or notifications (an object of settings), gettingStarted.skipped (a list of meta, invite, launch, loop, agent), gettingStarted.hidden (true or false) agentApprovals (when the in-app Agent asks before it acts: risky, the default, always or auto for Run everything) or agentMemory.autoSave (true: the in-app Agent saves what it suggests remembering without asking; only a person signed in to Pluto turns it on, 403 otherwise) or launch.lastAdAccount ({platform, adAccountId}: the ad account last chosen for a launch, which the account picker puts first) or sidebar.collapsed (true or false: the app's sidebar collapsed to its icon rail) or view.launches, view.launch, view.media, view.analytics, view.loops, view.inbox (what that list page shows the person: {state, default}, each the page's view state; PUT /views/pages/{page} checks the IDs too) or tableSorts ({table: {column, direction}}: the sort of the tables outside list pages, members, auditLog, metaAccounts); anything else is a 422. auto is 403 unless a person signed in to Pluto saves it, in a workspace that lets members (GET /agent/approval-settings) or as an owner or admin.

Permission: readGuests tooCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
keypathstringRequired
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

expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
valueanyRequired
Any JSON.

Response200 OK

The preference.

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 PUT "$PLUTO_API/preferences/launches.view" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 302b2100-5fa8-43cd-bfd9-d8bc8c6925f6" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "value": "4210.00"
  }'