API reference

Statuses

The review statuses ads move through.

GET/workflow/statuses

List review statuses

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

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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.
  • 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/workflow/statuses" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/workflow/statuses

Create a review status

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

categorystringRequired
Category.One of unstarted, started, completed, changes
colorstring
Marker color.
descriptionstring
Up to 160 characters.
idstring (uuid)
Optional client-chosen ID.
namestringRequired
Up to 40 characters.

Response201 Created

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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"
  }'
POST/workflow/statuses/reorder

Move a status to another's place

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

sourceIdstring (uuid)Required
Status to move.
targetIdstring (uuid)Required
Its new place.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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"
  }'
PATCH/workflow/statuses/{id}

Update a review status

Permission: writeCommand: send Idempotency-Key

Parameters

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

colorstring
Color.
descriptionstring
Description.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
namestring
Name.
positioninteger
Index in its category.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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/workflow/statuses/{id}

Delete an unused review status

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe status'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.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/workflow/statuses/069ff91e-35e1-4603-afc3-792b04f09624" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: aec47894-72b1-4b4a-b556-b78cd8d48fc6"
POST/workflow/statuses/{id}/archive

Archive a review status

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe status'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
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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
  }'
POST/workflow/statuses/{id}/default

Make a status the default

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe status'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
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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
  }'
POST/workflow/statuses/{id}/unarchive

Restore a review status

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe status'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
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

defaultStatusIdstring (uuid) or null
The default status for new ads.
statusesarray of objectsRequired
Statuses in display order.
statuses[].archivedboolean
Archived.
statuses[].archivedAtstring (date-time) or null
Archived at.
statuses[].categorystring
What the status means; fixed once created.One of unstarted, started, completed, changes
statuses[].colorstring
Color.
statuses[].descriptionstring
Description.
statuses[].idstring (uuid)Required
ID.
statuses[].isDefaultboolean
Default for new ads.
statuses[].namestring
Name.
statuses[].positioninteger
Order within the category.
statuses[].usageCountinteger
Ads in it.
statuses[].versioninteger
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 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/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
  }'