Defaults
What new campaigns and ad sets start with, per ad platform.
Get defaults
What a new campaign and a new ad set start with on an ad platform (meta, or another from GET /platforms, whose answer holds its spec's campaign and ad set fields): every setting's value, the keys the workspace chose (saved) and each level's version. On Meta the ad set level includes the launch settings ad sets inherit (pixel, conversion event, attribution, audience, placements, delivery), which are also part of GET /meta-defaults. A platform whose ads hold their own settings also answers ad: what a new ad starts with (such as the name it runs as, its tagline, button and link), its saved keys and its version; PATCH /defaults/{platform}/ad changes it. A platform whose launches carry their own URL parameters also answers launch: the URL parameters (utm) its new launches' ads carry, and on a platform that names its launch defaults there, the ad account a new launch uses (adAccountId), its name patterns (campaignNaming, adSetNaming, adNaming) and whether it publishes paused or enabled (delivery), and on a platform whose reads cost per item, its replies and leadSync switches (true until turned off). A platform that keeps defaults per ad account also answers accounts, by ad account ID: each account's settings (what a new launch on that ad account starts with where it has none of its own, such as the campaign, the identity ads run as or the funding source; the platform's spec names the keys), its saved keys and its version; PATCH /defaults/{platform}/accounts/{accountId} changes one.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
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
accounts- On a platform that keeps defaults per ad account: by ad account ID, what that account's new launches start with of its own (
settings), the keys it changes over the workspace's (saved) and its version. adad.saved- The keys the workspace chose; the rest are built in.
ad.settings- Every key with the value a new campaign or ad set starts with.
ad.version- 0 until first saved.
adSetadSet.saved- The keys the workspace chose; the rest are built in.
adSet.settings- Every key with the value a new campaign or ad set starts with.
adSet.version- 0 until first saved.
campaigncampaign.saved- The keys the workspace chose; the rest are built in.
campaign.settings- Every key with the value a new campaign or ad set starts with.
campaign.version- 0 until first saved.
launchlaunch.saved- The keys the workspace chose; the rest are built in.
launch.settings- Every key with the value a new campaign or ad set starts with.
launch.version- 0 until first saved.
platform- The platform (
GET /platforms).
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/defaults/59a4cf9d-a07f-4bfd-9d81-e8712666cabf" \
-H "Authorization: Bearer $PLUTO_KEY"Change an ad account's defaults
On a platform that keeps defaults per ad account (GET /defaults/{platform} answers accounts): the campaign settings new launches on this ad account start with, over the workspace's campaign defaults. It holds the keys the campaign level holds, an amount in the ad account's own currency, and what only this ad account knows (a custom conversion goal, a placement exclusion list, a lead form, an account asset). settings holds only the keys to change; null goes back to the workspace's value. Each key is checked by the platform's rules: a value that doesn't fit is refused with 422 on settings/<key>, in the platform's words. Send expectedVersion from accounts[accountId].version (0 while the account has none of its own); another change in between answers 409 with the current defaults. Defaults apply when a launch is created and never change existing ones. Any other platform answers 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
accountId | string | Required | The account'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 last read; 0 when the account has no defaults of its own.
settings- The keys to change;
nullremoves a key.
Response
accounts- On a platform that keeps defaults per ad account: by ad account ID, what that account's new launches start with of its own (
settings), the keys it changes over the workspace's (saved) and its version. adad.saved- The keys the workspace chose; the rest are built in.
ad.settings- Every key with the value a new campaign or ad set starts with.
ad.version- 0 until first saved.
adSetadSet.saved- The keys the workspace chose; the rest are built in.
adSet.settings- Every key with the value a new campaign or ad set starts with.
adSet.version- 0 until first saved.
campaigncampaign.saved- The keys the workspace chose; the rest are built in.
campaign.settings- Every key with the value a new campaign or ad set starts with.
campaign.version- 0 until first saved.
launchlaunch.saved- The keys the workspace chose; the rest are built in.
launch.settings- Every key with the value a new campaign or ad set starts with.
launch.version- 0 until first saved.
platform- The platform (
GET /platforms).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account that's on, or the platform keeps no defaults per ad account.
- 409The account's defaults changed since
expectedVersion(the body carriescurrent). - 422A value doesn't fit, or the campaign level doesn't hold it.
- 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/defaults/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/accounts/4ba13b16-127b-4f23-9f2e-7f1d5379786d" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 440e47f5-7bad-410e-ae20-79d9ca9f8385" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"settings": {}
}'Clear an ad account's defaults
New launches on this ad account follow the workspace's campaign defaults again. Clearing an ad account without defaults of its own changes nothing. Any other platform answers 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
accountId | string | Required | The account'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
accounts- On a platform that keeps defaults per ad account: by ad account ID, what that account's new launches start with of its own (
settings), the keys it changes over the workspace's (saved) and its version. adad.saved- The keys the workspace chose; the rest are built in.
ad.settings- Every key with the value a new campaign or ad set starts with.
ad.version- 0 until first saved.
adSetadSet.saved- The keys the workspace chose; the rest are built in.
adSet.settings- Every key with the value a new campaign or ad set starts with.
adSet.version- 0 until first saved.
campaigncampaign.saved- The keys the workspace chose; the rest are built in.
campaign.settings- Every key with the value a new campaign or ad set starts with.
campaign.version- 0 until first saved.
launchlaunch.saved- The keys the workspace chose; the rest are built in.
launch.settings- Every key with the value a new campaign or ad set starts with.
launch.version- 0 until first saved.
platform- The platform (
GET /platforms).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account that's on, or the platform keeps no defaults per ad account.
- 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/defaults/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/accounts/4ba13b16-127b-4f23-9f2e-7f1d5379786d" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8c9d9245-a33d-46b9-b536-2998accf0d5d"Change defaults
level is campaign or ad-set, ad on a platform whose ads hold their own settings (GET /defaults/{platform} answers ad), and launch on a platform whose launches carry their own URL parameters (GET /defaults/{platform} answers launch): it takes utm, at most 2,000 characters (2,048 where the platform says so), with only the values that platform fills (any other is refused), and where the platform names them there, adAccountId (an ad account that's on), campaignNaming (only {{date}}), adSetNaming and adNaming (up to 120 characters each) and delivery (Paused or Active), and where the platform has them replies and leadSync (true or false; false stops reading replies or leads there, and null turns it back on). On a platform with defaults per ad account, campaign and ad-set refuse what one ad account names (such as its funding source, identity, conversion event or lead form) and the dates, which a launch holds. A platform whose ad set fields are templates' only refuses ad-set with 422 on each key, and a setting that belongs to one ad account (a custom goal, a list, an asset, a profile, a pixel or an app of that account) is refused at the workspace's level: set it in that account's defaults (PATCH /defaults/{platform}/accounts/{accountId}). settings holds only the keys to change; null restores a key's built-in value. Every invalid key is reported at once. Defaults apply when something is created and never change existing campaigns or ad sets. On Meta, money (budget, bidAmount) is a decimal string in currency and applies only to ad accounts in that currency; on a platform with its own launch settings an amount carries no currency and applies in each ad account's own, so it's refused (422) while that platform's ad accounts that are on bill in several currencies.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
level | string | Required | |
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.
settings- Keys to change.
Response
accounts- On a platform that keeps defaults per ad account: by ad account ID, what that account's new launches start with of its own (
settings), the keys it changes over the workspace's (saved) and its version. adad.saved- The keys the workspace chose; the rest are built in.
ad.settings- Every key with the value a new campaign or ad set starts with.
ad.version- 0 until first saved.
adSetadSet.saved- The keys the workspace chose; the rest are built in.
adSet.settings- Every key with the value a new campaign or ad set starts with.
adSet.version- 0 until first saved.
campaigncampaign.saved- The keys the workspace chose; the rest are built in.
campaign.settings- Every key with the value a new campaign or ad set starts with.
campaign.version- 0 until first saved.
launchlaunch.saved- The keys the workspace chose; the rest are built in.
launch.settings- Every key with the value a new campaign or ad set starts with.
launch.version- 0 until first saved.
platform- The platform (
GET /platforms).
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/defaults/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/6f1df4b8-b925-4851-90da-4e4ecb3be59e" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e1245c7a-e7ad-4f40-aa32-fe465b12fc97" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"settings": {}
}'