API reference

Views

Views: what a person sees on a list page (Launches, Media, Analytics, Loops, Inbox) as one view state of filters, grouping, ordering and display that is the page's URL, checked against the page's schema, and saved views, personal or shared with the workspace.

GET/views

List saved views

The saved views the acting person sees: the workspace's shared views and their own personal ones, shared first, then by name. Needs a person.

Permission: read

Parameters

NameTypeRequiredDescription
pagequerystringOptionalOnly this page's views: launches, launch, media, analytics, loops or inbox.
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
Shared first, then by name.
items[].createdAtstring (date-time)Required
Saved.
items[].idstring (uuid)Required
View.
items[].namestringRequired
Its name.
items[].ownerobjectRequired
items[].owner.idstring (uuid)Required
Who saved it.
items[].owner.namestring or nullRequired
Their name.
items[].pagestringRequired
Its page.One of launches, launch, media, analytics, loops, inbox
items[].pathstringRequired
The app path that opens it, with view=<id>.
items[].sharedbooleanRequired
Everyone in the workspace sees it; otherwise only its person.
items[].stateobjectRequired
Its view state (only what differs from the page's defaults).
items[].updatedAtstring (date-time)Required
Last changed.
items[].versionintegerRequired
Send it back as expectedVersion when changing it.

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/views" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/views

Save a view

Saves a page's view state under a name. Personal by default (only its person sees it); shared: true shows it to everyone in the workspace and needs write. Names are unique per page among the views the same people see, in any case. A saved view never names another one (view is dropped).

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

namestringRequired
Up to 80 characters.
pagestringRequired
The list page.One of launches, launch, media, analytics, loops, inbox
sharedboolean
Everyone in the workspace sees it (needs write).
stateobject
A page's view state: only the fields that differ from the page's defaults (lists as arrays of strings or comma-separated text, flags as booleans). Every page's fields, values and defaults are in GET /views/schema. Unknown fields, values the page doesn't take and IDs that aren't in the workspace are a 422 listing every problem (state/<field>).

Response201 Created

createdAtstring (date-time)Required
Saved.
idstring (uuid)Required
View.
namestringRequired
Its name.
ownerobjectRequired
owner.idstring (uuid)Required
Who saved it.
owner.namestring or nullRequired
Their name.
pagestringRequired
Its page.One of launches, launch, media, analytics, loops, inbox
pathstringRequired
The app path that opens it, with view=<id>.
sharedbooleanRequired
Everyone in the workspace sees it; otherwise only its person.
stateobjectRequired
Its view state (only what differs from the page's defaults).
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
Send it back as expectedVersion when changing it.

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/views" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 988957cb-4acc-404c-9122-d909567c8386" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vitamin C Serum, UGC 9x16",
    "page": "launches",
    "shared": true,
    "state": {}
  }'
POST/views/link

Check a view

Checks a view state against its page and answers with the app path and URL that show it, and the state as the page reads it. Changes nothing.

Permission: read

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

pagestringRequired
The list page.One of launches, launch, media, analytics, loops, inbox
stateobject
A page's view state: only the fields that differ from the page's defaults (lists as arrays of strings or comma-separated text, flags as booleans). Every page's fields, values and defaults are in GET /views/schema. Unknown fields, values the page doesn't take and IDs that aren't in the workspace are a 422 listing every problem (state/<field>).

Response200 OK

pagestringRequired
The page.
pathstringRequired
The app path (/loops?group=account).
stateobjectRequired
The state with only what differs from the defaults.
urlstringRequired
The whole link.

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 -X POST "$PLUTO_API/views/link" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": "launches",
    "state": {}
  }'
GET/views/pages

List page views

What each list page shows the acting person when they open it: the order and filters they left it with on any device (the search and the folder or launch it's on aren't kept), else their own default, else the page's. Also their default, who set it last (agent or app) and the link. Needs a person.

Permission: read

Parameters

NameTypeRequiredDescription
pagequerystringOptionalOnly this page: launches, launch, media, analytics, loops or inbox.
launchquerystringOptionalFor launch: the launch (or campaign) ID the link opens.
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
One per page.
items[].defaultobject or nullRequired
Their own default for the page; null for the page's.
items[].pagestringRequired
The page.One of launches, launch, media, analytics, loops, inbox
items[].pathstring or nullRequired
The app path that shows it (null for launch without a launch).
items[].setAtstring (date-time) or nullRequired
When.
items[].setBystring or nullRequired
Who set it last: an agent, or the person in the app; null when never set.One of agent, app
items[].sortsarray of objectsRequired
The orderings the page takes.
items[].sorts[].labelstringRequired
Its words in the app.
items[].sorts[].valuestringRequired
The sort value.
items[].stateobjectRequired
What it shows the person when they open it (only what differs from the page's defaults).
items[].titlestringRequired
Its name in the app.
items[].urlstring or nullRequired
The whole link.

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/views/pages" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/views/pages/{page}

Get a page view

What one list page shows the acting person, as GET /views/pages?page=. Needs a person.

Permission: read

Parameters

NameTypeRequiredDescription
pagepathstringRequired
launchquerystringOptionalFor launch: the launch (or campaign) ID the link opens.
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

defaultobject or nullRequired
Their own default for the page; null for the page's.
pagestringRequired
The page.One of launches, launch, media, analytics, loops, inbox
pathstring or nullRequired
The app path that shows it (null for launch without a launch).
setAtstring (date-time) or nullRequired
When.
setBystring or nullRequired
Who set it last: an agent, or the person in the app; null when never set.One of agent, app
sortsarray of objectsRequired
The orderings the page takes.
sorts[].labelstringRequired
Its words in the app.
sorts[].valuestringRequired
The sort value.
stateobjectRequired
What it shows the person when they open it (only what differs from the page's defaults).
titlestringRequired
Its name in the app.
urlstring or nullRequired
The whole link.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this 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/views/pages/65ed0584-aa3e-40e6-a062-786ca33d5821" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/views/pages/{page}

Set a page view

Sets the order and filters a list page shows the acting person from now on, on every device; a page they have open follows at once. The state is checked as in POST /views/link (every problem a 422, state/<field>); the search and the folder or launch in the path aren't kept, so the same order and filters follow them to every folder and launch. {} clears them back to the page's defaults. default: true also makes it their default for the page (Reset to default in the app returns to it); with defaultOnly, only the default changes. Needs a person.

Permission: readCommand: send Idempotency-Key

Parameters

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

defaultboolean
Also make it the person's default for the page.
defaultOnlyboolean
With default: change only the default, not what the page shows now.
launchstring
For launch: the launch (or campaign) ID the answer's link opens.
stateobject
A page's view state: only the fields that differ from the page's defaults (lists as arrays of strings or comma-separated text, flags as booleans). Every page's fields, values and defaults are in GET /views/schema. Unknown fields, values the page doesn't take and IDs that aren't in the workspace are a 422 listing every problem (state/<field>).

Response200 OK

defaultobject or nullRequired
Their own default for the page; null for the page's.
pagestringRequired
The page.One of launches, launch, media, analytics, loops, inbox
pathstring or nullRequired
The app path that shows it (null for launch without a launch).
setAtstring (date-time) or nullRequired
When.
setBystring or nullRequired
Who set it last: an agent, or the person in the app; null when never set.One of agent, app
sortsarray of objectsRequired
The orderings the page takes.
sorts[].labelstringRequired
Its words in the app.
sorts[].valuestringRequired
The sort value.
stateobjectRequired
What it shows the person when they open it (only what differs from the page's defaults).
titlestringRequired
Its name in the app.
urlstring or nullRequired
The whole link.

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/views/pages/65ed0584-aa3e-40e6-a062-786ca33d5821" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 32b6b0b9-d088-46a4-b09f-37c867555a0f" \
  -H "Content-Type: application/json" \
  -d '{
    "default": true,
    "defaultOnly": true,
    "launch": "launch",
    "state": {}
  }'
GET/views/schema

Get view schemas

The fields of each list page (Launches, a launch's ads, Media, Analytics, Loops, Inbox): key, label, kind (oneOf with values, ids with idKind and tokens, text, date, flag), whether it takes several values and its default. A view state is the page's URL: every field is a query parameter, a list is comma-separated, a flag is 1, a value equal to the default is left out, and Media's folder is the path (/media/folders/{id}), as is a launch page's launch (/launches/{id}).

Permission: read

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

pagesarray of objectsRequired
Each page with page, title, path, pathField and fields.

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/views/schema" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/views/{id}

Get a saved view

A personal view of someone else is a 404.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe view's ID.
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

createdAtstring (date-time)Required
Saved.
idstring (uuid)Required
View.
namestringRequired
Its name.
ownerobjectRequired
owner.idstring (uuid)Required
Who saved it.
owner.namestring or nullRequired
Their name.
pagestringRequired
Its page.One of launches, launch, media, analytics, loops, inbox
pathstringRequired
The app path that opens it, with view=<id>.
sharedbooleanRequired
Everyone in the workspace sees it; otherwise only its person.
stateobjectRequired
Its view state (only what differs from the page's defaults).
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
Send it back as expectedVersion when changing it.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this 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/views/43200b01-4759-4c6a-9932-6a825787d393" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/views/{id}

Change a saved view

Renames it, replaces its state or shares it. A shared view needs write to change; only its person makes it personal again (403). Give the version you read as expectedVersion: a view changed since is a 409 with the view as it is.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe view'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

expectedVersionintegerRequired
The version you read.
namestring
Its new name.
sharedboolean
Shared with the workspace, or only its person.
stateobject
A page's view state: only the fields that differ from the page's defaults (lists as arrays of strings or comma-separated text, flags as booleans). Every page's fields, values and defaults are in GET /views/schema. Unknown fields, values the page doesn't take and IDs that aren't in the workspace are a 422 listing every problem (state/<field>).

Response200 OK

createdAtstring (date-time)Required
Saved.
idstring (uuid)Required
View.
namestringRequired
Its name.
ownerobjectRequired
owner.idstring (uuid)Required
Who saved it.
owner.namestring or nullRequired
Their name.
pagestringRequired
Its page.One of launches, launch, media, analytics, loops, inbox
pathstringRequired
The app path that opens it, with view=<id>.
sharedbooleanRequired
Everyone in the workspace sees it; otherwise only its person.
stateobjectRequired
Its view state (only what differs from the page's defaults).
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
Send it back as expectedVersion when changing it.

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/views/43200b01-4759-4c6a-9932-6a825787d393" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 7c653c46-139c-4420-ad29-cd515cb3397e" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "name": "Vitamin C Serum, UGC 9x16",
    "shared": true,
    "state": {}
  }'
DELETE/views/{id}

Delete a saved view

Your own, or a shared one (needs write). expectedVersion is optional.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe view'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

expectedVersioninteger
Optional: the version you read.

Response200 OK

deletedbooleanRequired
Always true.
idstring (uuid)Required
The view.
namestringRequired
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 DELETE "$PLUTO_API/views/43200b01-4759-4c6a-9932-6a825787d393" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 6aef5bea-2e5e-4fd9-b1f4-92c9cd801829" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'