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.
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | string | Optional | Only this page's views: launches, launch, media, analytics, loops or inbox. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Shared first, then by name.
items[].createdAt- Saved.
items[].id- View.
items[].name- Its name.
items[].owneritems[].owner.id- Who saved it.
items[].owner.name- Their name.
items[].page- Its page.One of
launches,launch,media,analytics,loops,inbox items[].path- The app path that opens it, with
view=<id>. items[].shared- Everyone in the workspace sees it; otherwise only its person.
items[].state- Its view state (only what differs from the page's defaults).
items[].updatedAt- Last changed.
items[].version- Send it back as
expectedVersionwhen changing it.
curl "$PLUTO_API/views" \
-H "Authorization: Bearer $PLUTO_KEY"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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
name- Up to 80 characters.
page- The list page.One of
launches,launch,media,analytics,loops,inbox shared- Everyone in the workspace sees it (needs
write). state- 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>).
Response
createdAt- Saved.
id- View.
name- Its name.
ownerowner.id- Who saved it.
owner.name- Their name.
page- Its page.One of
launches,launch,media,analytics,loops,inbox path- The app path that opens it, with
view=<id>. shared- Everyone in the workspace sees it; otherwise only its person.
state- Its view state (only what differs from the page's defaults).
updatedAt- Last changed.
version- Send it back as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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": {}
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
page- The list page.One of
launches,launch,media,analytics,loops,inbox state- 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>).
Response
page- The page.
path- The app path (
/loops?group=account). state- The state with only what differs from the defaults.
url- The whole link.
curl -X POST "$PLUTO_API/views/link" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"page": "launches",
"state": {}
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | string | Optional | Only this page: launches, launch, media, analytics, loops or inbox. |
launch | string | Optional | For launch: the launch (or campaign) ID the link opens. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- One per page.
items[].default- Their own default for the page; null for the page's.
items[].page- The page.One of
launches,launch,media,analytics,loops,inbox items[].path- The app path that shows it (null for
launchwithout a launch). items[].setAt- When.
items[].setBy- Who set it last: an agent, or the person in the app; null when never set.One of
agent,app items[].sorts- The orderings the page takes.
items[].sorts[].label- Its words in the app.
items[].sorts[].value- The
sortvalue. items[].state- What it shows the person when they open it (only what differs from the page's defaults).
items[].title- Its name in the app.
items[].url- The whole link.
curl "$PLUTO_API/views/pages" \
-H "Authorization: Bearer $PLUTO_KEY"Get a page view
What one list page shows the acting person, as GET /views/pages?page=. Needs a person.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | string | Required | |
launch | string | Optional | For launch: the launch (or campaign) ID the link opens. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
default- Their own default for the page; null for the page's.
page- The page.One of
launches,launch,media,analytics,loops,inbox path- The app path that shows it (null for
launchwithout a launch). setAt- When.
setBy- Who set it last: an agent, or the person in the app; null when never set.One of
agent,app sorts- The orderings the page takes.
sorts[].label- Its words in the app.
sorts[].value- The
sortvalue. state- What it shows the person when they open it (only what differs from the page's defaults).
title- Its name in the app.
url- 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | string | Required | |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
default- Also make it the person's default for the page.
defaultOnly- With
default: change only the default, not what the page shows now. launch- For
launch: the launch (or campaign) ID the answer's link opens. state- 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>).
Response
default- Their own default for the page; null for the page's.
page- The page.One of
launches,launch,media,analytics,loops,inbox path- The app path that shows it (null for
launchwithout a launch). setAt- When.
setBy- Who set it last: an agent, or the person in the app; null when never set.One of
agent,app sorts- The orderings the page takes.
sorts[].label- Its words in the app.
sorts[].value- The
sortvalue. state- What it shows the person when they open it (only what differs from the page's defaults).
title- Its name in the app.
url- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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 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}).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
pages- Each page with
page,title,path,pathFieldandfields.
curl "$PLUTO_API/views/schema" \
-H "Authorization: Bearer $PLUTO_KEY"Get a saved view
A personal view of someone else is a 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The view's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- Saved.
id- View.
name- Its name.
ownerowner.id- Who saved it.
owner.name- Their name.
page- Its page.One of
launches,launch,media,analytics,loops,inbox path- The app path that opens it, with
view=<id>. shared- Everyone in the workspace sees it; otherwise only its person.
state- Its view state (only what differs from the page's defaults).
updatedAt- Last changed.
version- Send it back as
expectedVersionwhen 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The view's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
expectedVersion- The version you read.
name- Its new name.
shared- Shared with the workspace, or only its person.
state- 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>).
Response
createdAt- Saved.
id- View.
name- Its name.
ownerowner.id- Who saved it.
owner.name- Their name.
page- Its page.One of
launches,launch,media,analytics,loops,inbox path- The app path that opens it, with
view=<id>. shared- Everyone in the workspace sees it; otherwise only its person.
state- Its view state (only what differs from the page's defaults).
updatedAt- Last changed.
version- Send it back as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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 a saved view
Your own, or a shared one (needs write). expectedVersion is optional.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The view's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
expectedVersion- Optional: the version you read.
Response
deleted- Always true.
id- The view.
name- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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
}'