API reference

Inbox

Your notifications: read, archive and snooze them.

GET/inbox

List your inbox

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
kindquerystringOptionalKinds.
notKindquerystringOptionalExclude kinds.
fromquerystringOptionalActors.
notFromquerystringOptionalExclude actors.
launchquerystringOptionalLaunches.
notLaunchquerystringOptionalExclude launches.
statusquerystringOptionalStatuses.
notStatusquerystringOptionalExclude statuses.
unreadquerystringOptionalUnread only.
snoozedquerystringOptionalSnoozed.
groupedquerystringOptionalGroup by ad.
orderquerystringOptionalnewest (default) or oldest first, over every page; a cursor belongs to its order.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size.
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.
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/inbox" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/inbox/archive

Archive notifications

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 tooCommand: 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

idsarray of strings (uuid)Required
IDs.

Response200 OK

Updated count.

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/inbox/archive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 6470ef34-144a-437e-b81e-ccccc2fc7d03" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "b0182a4d-a8af-42b8-9fa8-fabdbd2b5ddc"
    ]
  }'
POST/inbox/read

Mark read

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 tooCommand: 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

allboolean
Everything.
idsarray of strings (uuid)
IDs.

Response200 OK

Updated count.

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/inbox/read" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: ebfc1826-5ad7-47b2-85b1-0410923f5222" \
  -H "Content-Type: application/json" \
  -d '{
    "all": true,
    "ids": [
      "b0182a4d-a8af-42b8-9fa8-fabdbd2b5ddc"
    ]
  }'
POST/inbox/snooze

Snooze notifications

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 tooCommand: 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

idsarray of strings (uuid)Required
IDs.
untilstring (date-time)Required
Until.

Response200 OK

Updated count.

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/inbox/snooze" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: f6c8fd11-5ee1-44ba-9327-96b9799506de" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "b0182a4d-a8af-42b8-9fa8-fabdbd2b5ddc"
    ],
    "until": "2026-09-30T13:00:00Z"
  }'
POST/inbox/unarchive

Unarchive notifications

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 tooCommand: 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

idsarray of strings (uuid)Required
IDs.

Response200 OK

Updated count.

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/inbox/unarchive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 24c48ead-5698-42da-b91d-ef15ff954b5e" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "b0182a4d-a8af-42b8-9fa8-fabdbd2b5ddc"
    ]
  }'
POST/inbox/unread

Mark unread

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 tooCommand: 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

idsarray of strings (uuid)Required
IDs.

Response200 OK

Updated count.

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/inbox/unread" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3ebb5cf5-87f5-40fd-bfc2-77636a36bd5d" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "b0182a4d-a8af-42b8-9fa8-fabdbd2b5ddc"
    ]
  }'
GET/inbox/unread-count

Count unread notifications

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

Counts.

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/inbox/unread-count" \
  -H "Authorization: Bearer $PLUTO_KEY"