Settings templates
Named campaign and ad set settings: start from them or apply them to ad sets.
List settings templates
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
level | string | Optional | campaign or ad_set; both when left out. |
platform | string | Optional | A platform from GET /platforms: only its templates. |
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
templates- Templates by name.
templates[].createdAt- Created.
templates[].id- ID.
templates[].issues- Values the platform no longer accepts: the template needs attention.
templates[].issues[].key- Setting.
templates[].issues[].message- What to change.
templates[].issues[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. templates[].issues[].messageParams- The values
messageCode's sentence names, present exactly when it is. templates[].level- Level.One of
campaign,ad_set templates[].name- Name.
templates[].platform- The ad platform it belongs to (
GET /platforms). templates[].settings- Only the settings the template sets.
templates[].updatedAt- Changed.
templates[].usestemplates[].uses.adSets- Ad sets.
templates[].uses.lastUsedAt- Last used.
templates[].uses.launches- Launches.
templates[].version- Version.
curl "$PLUTO_API/setting-templates" \
-H "Authorization: Bearer $PLUTO_KEY"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).
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
fromfrom.adSetId- An ad set.
from.launchId- A launch that creates its campaign.
id- Optional ID.
level- Campaign settings or ad set settings.One of
campaign,ad_set name- Up to 80 characters, unique per level.
platform- The ad platform, from
GET /platforms(defaultmeta). settings- The settings, by key.
Response
createdAt- Created.
id- ID.
issues- Values the platform no longer accepts: the template needs attention.
issues[].key- Setting.
issues[].message- What to change.
issues[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. issues[].messageParams- The values
messageCode's sentence names, present exactly when it is. level- Level.One of
campaign,ad_set name- Name.
platform- The ad platform it belongs to (
GET /platforms). settings- Only the settings the template sets.
updatedAt- Changed.
usesuses.adSets- Ad sets.
uses.lastUsedAt- Last used.
uses.launches- Launches.
version- 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 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/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 a settings template
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template's ID. |
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
createdAt- Created.
id- ID.
issues- Values the platform no longer accepts: the template needs attention.
issues[].key- Setting.
issues[].message- What to change.
issues[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. issues[].messageParams- The values
messageCode's sentence names, present exactly when it is. level- Level.One of
campaign,ad_set name- Name.
platform- The ad platform it belongs to (
GET /platforms). settings- Only the settings the template sets.
updatedAt- Changed.
usesuses.adSets- Ad sets.
uses.lastUsedAt- Last used.
uses.launches- Launches.
version- 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-Afterseconds. 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"Change a settings template
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template'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.
name- Name.
settings- Replaces the settings.
Response
createdAt- Created.
id- ID.
issues- Values the platform no longer accepts: the template needs attention.
issues[].key- Setting.
issues[].message- What to change.
issues[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. issues[].messageParams- The values
messageCode's sentence names, present exactly when it is. level- Level.One of
campaign,ad_set name- Name.
platform- The ad platform it belongs to (
GET /platforms). settings- Only the settings the template sets.
updatedAt- Changed.
usesuses.adSets- Ad sets.
uses.lastUsedAt- Last used.
uses.launches- Launches.
version- 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 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/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 a settings template
Ad sets and campaigns made with it keep their settings; history still names it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template'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
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 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/setting-templates/8835cba8-50eb-4e67-8d44-b89ac14a8b0f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c3f8b398-be35-499a-9e3f-699d609b8855"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template'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
adSetIds- Ad sets.
dryRun- Preview only.
launchIds- Launches.
Response
dryRun- Preview only.
targets- Per ad set or campaign.
targets[].changes- Changed settings.
targets[].changes[].key- Setting.
targets[].changes[].new- New value.
targets[].changes[].old- Old value.
targets[].id- The ad set, or the launch.
targets[].launchId- Launch.
targets[].level- Level.One of
campaign,ad_set targets[].name- Name.
targets[].skipped- Settings left alone.
targets[].skipped[].key- Setting.
targets[].skipped[].message- Why.
targets[].skipped[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. targets[].skipped[].messageParams- The values
messageCode's sentence names, present exactly when it is. templateId- 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 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/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"
]
}'Duplicate a template
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template'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
id- Optional ID.
name- Defaults to "<name> copy".
Response
createdAt- Created.
id- ID.
issues- Values the platform no longer accepts: the template needs attention.
issues[].key- Setting.
issues[].message- What to change.
issues[].messageCode- A registered
message's stable code (such assetting_template_currency_unknown), for an app to say it in its language; absent for a message without one. issues[].messageParams- The values
messageCode's sentence names, present exactly when it is. level- Level.One of
campaign,ad_set name- Name.
platform- The ad platform it belongs to (
GET /platforms). settings- Only the settings the template sets.
updatedAt- Changed.
usesuses.adSets- Ad sets.
uses.lastUsedAt- Last used.
uses.launches- Launches.
version- 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 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/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"
}'List template uses
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The setting template's ID. |
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
uses- Newest first.
uses[].adSetId- Ad set; null for a campaign.
uses[].adSetName- Ad set name.
uses[].launchId- Launch.
uses[].launchName- Launch name.
uses[].mode- Started from it, or applied to it.One of
created,applied uses[].usedAt- 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-Afterseconds. 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"