API reference

Settings templates

Named campaign and ad set settings: start from them or apply them to ad sets.

GET/setting-templates

List settings templates

Permission: read

Parameters

NameTypeRequiredDescription
levelquerystringOptionalcampaign or ad_set; both when left out.
platformquerystringOptionalA platform from GET /platforms: only its templates.
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 by name.
templates[].createdAtstring (date-time)Required
Created.
templates[].idstring (uuid)Required
ID.
templates[].issuesarray of objectsRequired
Values the platform no longer accepts: the template needs attention.
templates[].issues[].keystringRequired
Setting.
templates[].issues[].messagestringRequired
What to change.
templates[].issues[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
templates[].issues[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
templates[].levelstringRequired
Level.One of campaign, ad_set
templates[].namestringRequired
Name.
templates[].platformstringRequired
The ad platform it belongs to (GET /platforms).
templates[].settingsobjectRequired
Only the settings the template sets.
templates[].updatedAtstring (date-time)Required
Changed.
templates[].usesobjectRequired
templates[].uses.adSetsintegerRequired
Ad sets.
templates[].uses.lastUsedAtstring (date-time) or nullRequired
Last used.
templates[].uses.launchesintegerRequired
Launches.
templates[].versionintegerRequired
Version.

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/setting-templates" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/setting-templates

Create a settings template

A named campaign or ad set template, shared with the workspace. Send settings (only the keys it should set), or save an existing ad set or a launch's new campaign as a template with from (every setting it has, never its name, dates or creatives).

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

fromobject
from.adSetIdstring (uuid)
An ad set.
from.launchIdstring (uuid)
A launch that creates its campaign.
idstring (uuid)
Optional ID.
levelstring
Campaign settings or ad set settings.One of campaign, ad_set
namestringRequired
Up to 80 characters, unique per level.
platformstring
The ad platform, from GET /platforms (default meta).
settingsobject
The settings, by key.

Response201 Created

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
ID.
issuesarray of objectsRequired
Values the platform no longer accepts: the template needs attention.
issues[].keystringRequired
Setting.
issues[].messagestringRequired
What to change.
issues[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
issues[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
levelstringRequired
Level.One of campaign, ad_set
namestringRequired
Name.
platformstringRequired
The ad platform it belongs to (GET /platforms).
settingsobjectRequired
Only the settings the template sets.
updatedAtstring (date-time)Required
Changed.
usesobjectRequired
uses.adSetsintegerRequired
Ad sets.
uses.lastUsedAtstring (date-time) or nullRequired
Last used.
uses.launchesintegerRequired
Launches.
versionintegerRequired
Version.

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/setting-templates" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5589e202-318d-44cf-a0c9-d4a842c028cc" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
      "launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560"
    },
    "id": "8835cba8-50eb-4e67-8d44-b89ac14a8b0f",
    "level": "campaign",
    "name": "Vitamin C Serum, UGC 9x16",
    "platform": "meta",
    "settings": {}
  }'
GET/setting-templates/{id}

Get a settings template

Permission: read

Parameters

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

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
ID.
issuesarray of objectsRequired
Values the platform no longer accepts: the template needs attention.
issues[].keystringRequired
Setting.
issues[].messagestringRequired
What to change.
issues[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
issues[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
levelstringRequired
Level.One of campaign, ad_set
namestringRequired
Name.
platformstringRequired
The ad platform it belongs to (GET /platforms).
settingsobjectRequired
Only the settings the template sets.
updatedAtstring (date-time)Required
Changed.
usesobjectRequired
uses.adSetsintegerRequired
Ad sets.
uses.lastUsedAtstring (date-time) or nullRequired
Last used.
uses.launchesintegerRequired
Launches.
versionintegerRequired
Version.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this 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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/setting-templates/{id}

Change a settings template

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe setting 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

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
namestring
Name.
settingsobject
Replaces the settings.

Response200 OK

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
ID.
issuesarray of objectsRequired
Values the platform no longer accepts: the template needs attention.
issues[].keystringRequired
Setting.
issues[].messagestringRequired
What to change.
issues[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
issues[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
levelstringRequired
Level.One of campaign, ad_set
namestringRequired
Name.
platformstringRequired
The ad platform it belongs to (GET /platforms).
settingsobjectRequired
Only the settings the template sets.
updatedAtstring (date-time)Required
Changed.
usesobjectRequired
uses.adSetsintegerRequired
Ad sets.
uses.lastUsedAtstring (date-time) or nullRequired
Last used.
uses.launchesintegerRequired
Launches.
versionintegerRequired
Version.

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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 33fd05f5-4884-4c33-bada-914fffb7c1ac" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "name": "Vitamin C Serum, UGC 9x16",
    "settings": {}
  }'
DELETE/setting-templates/{id}

Delete a settings template

Ad sets and campaigns made with it keep their settings; history still names it.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe setting 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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: c3f8b398-be35-499a-9e3f-699d609b8855"
POST/setting-templates/{id}/apply

Apply a settings template

Applies an ad set template to existing ad sets (adSetIds) or a campaign template to launches' new campaigns (launchIds), up to 200. Only the keys the template sets change; each change is recorded with its old and new value and who made it. Amounts in another currency and a performance goal the campaign's objective lacks are left alone and listed in skipped. dryRun: true returns the same result without changing anything.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe setting 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

adSetIdsarray of strings (uuid)
Ad sets.
dryRunboolean
Preview only.
launchIdsarray of strings (uuid)
Launches.

Response200 OK

dryRunbooleanRequired
Preview only.
targetsarray of objectsRequired
Per ad set or campaign.
targets[].changesarray of objectsRequired
Changed settings.
targets[].changes[].keystringRequired
Setting.
targets[].changes[].newobjectRequired
New value.
targets[].changes[].oldobjectRequired
Old value.
targets[].idstring (uuid)Required
The ad set, or the launch.
targets[].launchIdstring (uuid)Required
Launch.
targets[].levelstringRequired
Level.One of campaign, ad_set
targets[].namestringRequired
Name.
targets[].skippedarray of objectsRequired
Settings left alone.
targets[].skipped[].keystringRequired
Setting.
targets[].skipped[].messagestringRequired
Why.
targets[].skipped[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
targets[].skipped[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
templateIdstring (uuid)Required
Template.

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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f/apply" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 880b995d-911b-4148-9f4f-8f06c7207ab3" \
  -H "Content-Type: application/json" \
  -d '{
    "adSetIds": [
      "dee201f4-1aee-4807-a122-f5e3b69d0753"
    ],
    "dryRun": false,
    "launchIds": [
      "2046ac37-4775-4757-9ef2-3d948cbfc560"
    ]
  }'
POST/setting-templates/{id}/duplicate

Duplicate a template

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe setting 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

idstring (uuid)
Optional ID.
namestring
Defaults to "<name> copy".

Response201 Created

createdAtstring (date-time)Required
Created.
idstring (uuid)Required
ID.
issuesarray of objectsRequired
Values the platform no longer accepts: the template needs attention.
issues[].keystringRequired
Setting.
issues[].messagestringRequired
What to change.
issues[].messageCodestring
A registered message's stable code (such as setting_template_currency_unknown), for an app to say it in its language; absent for a message without one.
issues[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
levelstringRequired
Level.One of campaign, ad_set
namestringRequired
Name.
platformstringRequired
The ad platform it belongs to (GET /platforms).
settingsobjectRequired
Only the settings the template sets.
updatedAtstring (date-time)Required
Changed.
usesobjectRequired
uses.adSetsintegerRequired
Ad sets.
uses.lastUsedAtstring (date-time) or nullRequired
Last used.
uses.launchesintegerRequired
Launches.
versionintegerRequired
Version.

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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f/duplicate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 472124f4-83c2-431d-9694-ee457a4cb4ef" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "8835cba8-50eb-4e67-8d44-b89ac14a8b0f",
    "name": "Vitamin C Serum, UGC 9x16"
  }'
GET/setting-templates/{id}/uses

List template uses

Permission: read

Parameters

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

usesarray of objectsRequired
Newest first.
uses[].adSetIdstring (uuid) or null
Ad set; null for a campaign.
uses[].adSetNamestring or null
Ad set name.
uses[].launchIdstring (uuid)Required
Launch.
uses[].launchNamestring or null
Launch name.
uses[].modestringRequired
Started from it, or applied to it.One of created, applied
uses[].usedAtstring (date-time)Required
When.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this 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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f/uses" \
  -H "Authorization: Bearer $PLUTO_KEY"