API reference

Defaults

What new campaigns and ad sets start with, per ad platform.

GET/defaults/{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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
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

accountsmap of object
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.
adobject
ad.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
ad.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
ad.versionintegerRequired
0 until first saved.
adSetobjectRequired
adSet.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
adSet.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
adSet.versionintegerRequired
0 until first saved.
campaignobjectRequired
campaign.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
campaign.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
campaign.versionintegerRequired
0 until first saved.
launchobject
launch.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
launch.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
launch.versionintegerRequired
0 until first saved.
platformstringRequired
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-After seconds. 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"
PATCH/defaults/{platform}/accounts/{accountId}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
platformpathstringRequired
accountIdpathstringRequiredThe account'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 last read; 0 when the account has no defaults of its own.
settingsobjectRequired
The keys to change; null removes a key.

Response200 OK

accountsmap of object
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.
adobject
ad.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
ad.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
ad.versionintegerRequired
0 until first saved.
adSetobjectRequired
adSet.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
adSet.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
adSet.versionintegerRequired
0 until first saved.
campaignobjectRequired
campaign.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
campaign.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
campaign.versionintegerRequired
0 until first saved.
launchobject
launch.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
launch.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
launch.versionintegerRequired
0 until first saved.
platformstringRequired
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 carries current).
  • 422A value doesn't fit, or the campaign level doesn't hold it.
  • 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/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": {}
  }'
DELETE/defaults/{platform}/accounts/{accountId}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
platformpathstringRequired
accountIdpathstringRequiredThe account'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.

Response200 OK

accountsmap of object
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.
adobject
ad.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
ad.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
ad.versionintegerRequired
0 until first saved.
adSetobjectRequired
adSet.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
adSet.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
adSet.versionintegerRequired
0 until first saved.
campaignobjectRequired
campaign.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
campaign.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
campaign.versionintegerRequired
0 until first saved.
launchobject
launch.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
launch.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
launch.versionintegerRequired
0 until first saved.
platformstringRequired
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 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/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"
PATCH/defaults/{platform}/{level}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
platformpathstringRequired
levelpathstringRequired
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.
settingsobjectRequired
Keys to change.

Response200 OK

accountsmap of object
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.
adobject
ad.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
ad.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
ad.versionintegerRequired
0 until first saved.
adSetobjectRequired
adSet.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
adSet.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
adSet.versionintegerRequired
0 until first saved.
campaignobjectRequired
campaign.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
campaign.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
campaign.versionintegerRequired
0 until first saved.
launchobject
launch.savedarray of stringsRequired
The keys the workspace chose; the rest are built in.
launch.settingsobjectRequired
Every key with the value a new campaign or ad set starts with.
launch.versionintegerRequired
0 until first saved.
platformstringRequired
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 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/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": {}
  }'