API reference

Copy templates

Reusable ad copy.

GET/templates

List copy templates

Permission: read

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

templatesarray of objectsRequired
Templates.
templates[].callToActionstring or null
CTA; null keeps the launch's.
templates[].createdAtstring (date-time)
Created.
templates[].descriptionstring or null
Description.
templates[].headlinestring
Headline.
templates[].idstring (uuid)Required
ID.
templates[].namestring
Name.
templates[].primaryTextstring
Primary text.
templates[].summarystring
Summary.
templates[].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/templates" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/templates

Create a copy template

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

callToActionstring or null
CTA.
descriptionstring or null
Description.
headlinestringRequired
Headline.
idstring (uuid)
Optional ID.
namestringRequired
Name.
primaryTextstringRequired
Primary text.
summarystring
Summary.

Response201 Created

callToActionstring or null
CTA; null keeps the launch's.
createdAtstring (date-time)
Created.
descriptionstring or null
Description.
headlinestring
Headline.
idstring (uuid)Required
ID.
namestring
Name.
primaryTextstring
Primary text.
summarystring
Summary.
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/templates" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 7a2b0d7a-2f49-4d6e-9935-009460d67de6" \
  -H "Content-Type: application/json" \
  -d '{
    "callToAction": "SHOP_NOW",
    "description": "Two drops every morning for brighter, even skin.",
    "headline": "Brighter skin in 14 days",
    "id": "a39ffff6-3eab-4880-baee-3e4e46b858d6",
    "name": "Fall offer",
    "primaryText": "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50.",
    "summary": "Spend is up 12% on the week; the UGC 9x16 ad leads on purchases."
  }'
PATCH/templates/{id}

Update a copy template

Permission: writeCommand: send Idempotency-Key

Parameters

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

callToActionstring or null
CTA.
descriptionstring or null
Description.
expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
headlinestring
Headline.
idstring (uuid)
Create: optional ID.
namestring
Name.
primaryTextstring
Primary text.
summarystring
Summary.

Response200 OK

callToActionstring or null
CTA; null keeps the launch's.
createdAtstring (date-time)
Created.
descriptionstring or null
Description.
headlinestring
Headline.
idstring (uuid)Required
ID.
namestring
Name.
primaryTextstring
Primary text.
summarystring
Summary.
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/templates/a39ffff6-3eab-4880-baee-3e4e46b858d6" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 81ddd2ac-f77b-4139-8d11-86edaba57772" \
  -H "Content-Type: application/json" \
  -d '{
    "callToAction": "SHOP_NOW",
    "description": "Two drops every morning for brighter, even skin.",
    "expectedVersion": 3,
    "headline": "Brighter skin in 14 days",
    "id": "a39ffff6-3eab-4880-baee-3e4e46b858d6",
    "name": "Fall offer",
    "primaryText": "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50.",
    "summary": "Spend is up 12% on the week; the UGC 9x16 ad leads on purchases."
  }'
DELETE/templates/{id}

Delete a copy template

Permission: writeCommand: send Idempotency-Key

Parameters

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

Response204 No Content

Done; no content.

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/templates/a39ffff6-3eab-4880-baee-3e4e46b858d6" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 8b374f0b-7ae5-4153-aa4a-2c2e9e2847e4"