API reference

Launch defaults

The Meta settings new launches start from, for the workspace and per ad account.

GET/meta-defaults

Get the launch defaults

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

accountsobjectRequired
Per ad account: overrides, effective settings, version.
settingsobjectRequired
Workspace defaults.
versionintegerRequired
0 until saved.

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/meta-defaults" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/meta-defaults

Set the launch defaults

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

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
settingsobjectRequired
Keys to change.

Response200 OK

accountsobjectRequired
Per ad account: overrides, effective settings, version.
settingsobjectRequired
Workspace defaults.
versionintegerRequired
0 until saved.

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 PUT "$PLUTO_API/meta-defaults" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3d2c3ac8-1f7f-4172-b9a3-98572c0e1a88" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "settings": {}
  }'
PUT/meta-defaults/accounts/{ad_account_id}

Set an ad account's defaults

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
ad_account_idpathstringRequiredThe ad 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 you last read. A mismatch is a conflict that returns the current entity.
settingsobjectRequired
Keys to change.

Response200 OK

accountsobjectRequired
Per ad account: overrides, effective settings, version.
settingsobjectRequired
Workspace defaults.
versionintegerRequired
0 until saved.

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 PUT "$PLUTO_API/meta-defaults/accounts/act_741877585619437" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 40a4c6e8-a3c1-4d70-b51b-afdb782a22ba" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "settings": {}
  }'
DELETE/meta-defaults/accounts/{ad_account_id}

Remove an ad account's defaults

Drop an ad account's overrides.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
ad_account_idpathstringRequiredThe ad 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

accountsobjectRequired
Per ad account: overrides, effective settings, version.
settingsobjectRequired
Workspace defaults.
versionintegerRequired
0 until saved.

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/meta-defaults/accounts/act_741877585619437" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 97e07746-e05a-4e5c-b912-a12c2f2b2348"