Statuses
The review statuses ads move through.
List review statuses
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
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
curl "$PLUTO_API/workflow/statuses" \
-H "Authorization: Bearer $PLUTO_KEY"Create a review status
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
category- Category.One of
unstarted,started,completed,changes color- Marker color.
description- Up to 160 characters.
id- Optional client-chosen ID.
name- Up to 40 characters.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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/workflow/statuses" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ec7ff583-e6da-44eb-816c-2fba526f33ee" \
-H "Content-Type: application/json" \
-d '{
"category": "unstarted",
"color": "#D9B48A",
"description": "Two drops every morning for brighter, even skin.",
"id": "e80a4b6c-a649-4529-9df7-ce6804cd0f11",
"name": "In review"
}'Move a status to another's place
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
sourceId- Status to move.
targetId- Its new place.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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/workflow/statuses/reorder" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 249a446e-0169-4e13-af5c-de92c9dd968a" \
-H "Content-Type: application/json" \
-d '{
"sourceId": "5b14a3a8-e140-44ae-b582-b88b2219a651",
"targetId": "01af096e-7668-46f6-8a67-e1ee7742b6fc"
}'Update a review status
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The status'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
color- Color.
description- Description.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
name- Name.
position- Index in its category.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9e65e908-f232-4ec4-99d0-64f7d5c67f4a" \
-H "Content-Type: application/json" \
-d '{
"color": "#D9B48A",
"description": "Two drops every morning for brighter, even skin.",
"expectedVersion": 3,
"name": "In review",
"position": 0
}'Delete an unused review status
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The status'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. |
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: aec47894-72b1-4b4a-b556-b78cd8d48fc6"Archive a review status
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The status'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 last read. A mismatch is a conflict that returns the current entity.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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 POST "$PLUTO_API/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3bcd3582-0fb2-4c9f-a0cc-84369a5cd7d3" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Make a status the default
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The status'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 last read. A mismatch is a conflict that returns the current entity.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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 POST "$PLUTO_API/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624/default" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 6cc6b9ce-3686-49f2-992e-7bda43ebd741" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Restore a review status
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The status'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 last read. A mismatch is a conflict that returns the current entity.
Response
defaultStatusId- The default status for new ads.
statuses- Statuses in display order.
statuses[].archived- Archived.
statuses[].archivedAt- Archived at.
statuses[].category- What the status means; fixed once created.One of
unstarted,started,completed,changes statuses[].color- Color.
statuses[].description- Description.
statuses[].id- ID.
statuses[].isDefault- Default for new ads.
statuses[].name- Name.
statuses[].position- Order within the category.
statuses[].usageCount- Ads in it.
statuses[].version- Increments on every change; send as
expectedVersion.
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 POST "$PLUTO_API/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624/unarchive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 81616e15-28d2-41a8-b697-91987a92b319" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'