API reference

Bulk edits

Bulk edits applied to ad sets and ads, and reverting them.

GET/changesets

List bulk edits

The workspace's bulk edits (applies and reverts), newest first, each with whether it can still be undone.

Permission: read

Parameters

NameTypeRequiredDescription
minequerystringOptionalfalse for everyone's; default: only the caller's own.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-100, default 20).
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

itemsarray of objectsRequired
This page.
items[].actorIdstring (uuid)Required
Their ID.
items[].actorKindstringRequired
Who made it: person, agent or api_key.
items[].applyingbooleanRequired
Still being applied.
items[].canUndobooleanRequired
Whether a revert would start now: the credential may write, it wasn't undone and isn't still applying.
items[].createdAtstring (date-time)Required
When.
items[].entitiesarray of stringsRequired
What it changed.
items[].fieldsarray of stringsRequired
The fields it changed.
items[].idstring (uuid)Required
Changeset.
items[].itemsintegerRequired
Ads or ad sets it changed.
items[].kindstringRequired
revert when it undid another bulk edit (reverts).One of edit, revert
items[].revertedBystring (uuid) or null
The changeset that undid it.
items[].revertsstring (uuid) or null
The bulk edit it undid.
items[].summarystringRequired
What changed, in words.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

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/changesets" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/changesets/{id}

Get a bulk edit

A changeset: who changed what.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe changeset'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

actorIdstring (uuid)Required
Their ID.
actorKindstringRequired
Who made it: person, agent or api_key.
createdAtstring (date-time)Required
When.
entriesarray of objectsRequired
Before/after per item and field.
entries[].afterany
Value after (any JSON); null when unset.
entries[].beforeany
Value before (any JSON); null when unset.
entries[].entitystringRequired
ad or ad_set.
entries[].entityIdstring (uuid)Required
Item.
entries[].fieldstringRequired
Field.
entries[].versionAfterintegerRequired
The item's version after the change; a revert applies only while it is still current.
idstring (uuid)Required
Changeset.
revertedBystring (uuid) or null
The changeset that reverted it.
selectorobjectRequired
The selector the edit resolved.
summarystringRequired
What changed, in words.

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/changesets/da17397c-759e-4179-916f-87cbbcd79e42" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/changesets/{id}/revert

Revert a bulk edit

Restores items unchanged since; the rest come back as conflicts. Provider effects are not undone. Runs in chunks like an apply.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe changeset'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

Reverted count and conflicts.

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/changesets/da17397c-759e-4179-916f-87cbbcd79e42/revert" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: b9cd7f2c-34bb-4c5d-841d-566116aa48f9"