API reference

Tags

Tags for ads.

GET/workflow/labels

List labels

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

labelsarray of objectsRequired
Labels.
labels[].archivedboolean
Archived.
labels[].archivedAtstring (date-time) or null
Archived at.
labels[].colorstring
Color.
labels[].createdAtstring (date-time)
Created.
labels[].descriptionstring
Description.
labels[].idstring (uuid)Required
ID.
labels[].lastAppliedAtstring (date-time) or null
Last applied to an ad; never inferred.
labels[].namestring
Name.
labels[].usageCountinteger
Ads carrying it.
labels[].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/labels" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/workflow/labels

Create a label

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

colorstring
Color.
descriptionstring
Description.
idstring (uuid)
Optional ID.
namestringRequired
Name.

Response201 Created

archivedboolean
Archived.
archivedAtstring (date-time) or null
Archived at.
colorstring
Color.
createdAtstring (date-time)
Created.
descriptionstring
Description.
idstring (uuid)Required
ID.
lastAppliedAtstring (date-time) or null
Last applied to an ad; never inferred.
namestring
Name.
usageCountinteger
Ads carrying it.
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/labels" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: da5e8948-cc05-4e3b-8af3-e188d2ba082a" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#D9B48A",
    "description": "Two drops every morning for brighter, even skin.",
    "id": "e80a4b6c-a649-4529-9df7-ce6804cd0f11",
    "name": "In review"
  }'
POST/workflow/labels/delete

Delete several labels

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

idsarray of strings (uuid)Required
Labels to delete.

Response200 OK

ids, detachedCount.

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/labels/delete" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 223e60a4-3849-4bb7-8fac-c477277aadce" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "e80a4b6c-a649-4529-9df7-ce6804cd0f11"
    ]
  }'
PATCH/workflow/labels/{id}

Update a label

Permission: writeCommand: send Idempotency-Key

Parameters

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

Response200 OK

archivedboolean
Archived.
archivedAtstring (date-time) or null
Archived at.
colorstring
Color.
createdAtstring (date-time)
Created.
descriptionstring
Description.
idstring (uuid)Required
ID.
lastAppliedAtstring (date-time) or null
Last applied to an ad; never inferred.
namestring
Name.
usageCountinteger
Ads carrying it.
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/labels/3b3e38bc-b355-4d75-a044-270c99d48ced" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 84aaf2b4-737e-4704-b448-2433e57cbda8" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#D9B48A",
    "description": "Two drops every morning for brighter, even skin.",
    "expectedVersion": 3,
    "name": "In review"
  }'
DELETE/workflow/labels/{id}

Delete a label

Permission: writeCommand: send Idempotency-Key

Parameters

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

ids, detachedCount.

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/labels/3b3e38bc-b355-4d75-a044-270c99d48ced" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: e8ef1635-9af9-42ae-aa4f-8a3c9160677b"
POST/workflow/labels/{id}/archive

Archive a label

Permission: writeCommand: send Idempotency-Key

Parameters

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

archivedboolean
Archived.
archivedAtstring (date-time) or null
Archived at.
colorstring
Color.
createdAtstring (date-time)
Created.
descriptionstring
Description.
idstring (uuid)Required
ID.
lastAppliedAtstring (date-time) or null
Last applied to an ad; never inferred.
namestring
Name.
usageCountinteger
Ads carrying it.
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/labels/3b3e38bc-b355-4d75-a044-270c99d48ced/archive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: c7ade8b3-1754-46cd-ae13-892192275678" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'
POST/workflow/labels/{id}/unarchive

Restore a label

Permission: writeCommand: send Idempotency-Key

Parameters

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

archivedboolean
Archived.
archivedAtstring (date-time) or null
Archived at.
colorstring
Color.
createdAtstring (date-time)
Created.
descriptionstring
Description.
idstring (uuid)Required
ID.
lastAppliedAtstring (date-time) or null
Last applied to an ad; never inferred.
namestring
Name.
usageCountinteger
Ads carrying it.
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/labels/3b3e38bc-b355-4d75-a044-270c99d48ced/unarchive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 883168f5-2aac-40bf-958c-4d212fdf2e86" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'