Tags
Tags for ads.
List labels
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
labels- Labels.
labels[].archived- Archived.
labels[].archivedAt- Archived at.
labels[].color- Color.
labels[].createdAt- Created.
labels[].description- Description.
labels[].id- ID.
labels[].lastAppliedAt- Last applied to an ad; never inferred.
labels[].name- Name.
labels[].usageCount- Ads carrying it.
labels[].version- Increments on every change; send as
expectedVersion.
curl "$PLUTO_API/workflow/labels" \
-H "Authorization: Bearer $PLUTO_KEY"Create a label
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
color- Color.
description- Description.
id- Optional ID.
name- Name.
Response
archived- Archived.
archivedAt- Archived at.
color- Color.
createdAt- Created.
description- Description.
id- ID.
lastAppliedAt- Last applied to an ad; never inferred.
name- Name.
usageCount- Ads carrying it.
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/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"
}'Delete several labels
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
ids- Labels to delete.
Response
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 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/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"
]
}'Update a label
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The label'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.
Response
archived- Archived.
archivedAt- Archived at.
color- Color.
createdAt- Created.
description- Description.
id- ID.
lastAppliedAt- Last applied to an ad; never inferred.
name- Name.
usageCount- Ads carrying it.
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/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 a label
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The label'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
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 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/labels/3b3e38bc-b355-4d75-a044-270c99d48ced" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e8ef1635-9af9-42ae-aa4f-8a3c9160677b"Archive a label
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The label'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
archived- Archived.
archivedAt- Archived at.
color- Color.
createdAt- Created.
description- Description.
id- ID.
lastAppliedAt- Last applied to an ad; never inferred.
name- Name.
usageCount- Ads carrying it.
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/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
}'Restore a label
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The label'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
archived- Archived.
archivedAt- Archived at.
color- Color.
createdAt- Created.
description- Description.
id- ID.
lastAppliedAt- Last applied to an ad; never inferred.
name- Name.
usageCount- Ads carrying it.
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/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
}'