API reference

Mirrors

Connections: the ad platforms (GET /platforms) and the store's profit (Pluto Profit).

GET/mirrors/{platform}

Get Keep in sync

Keep in sync for Meta (meta; it mirrors no other platform yet: 404): whether every campaign that isn't archived or deleted of the chosen ad accounts is kept in Pluto as a launch, with its ad sets, ads and their images and videos in the Media library (From Meta), and how it's doing: campaigns in sync, the run in progress, and campaigns that wait for a launch's unpublished changes or failed, with why. Without a stored choice it is on for every ad account.

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

adAccountIdsarray of strings or nullRequired
The ad accounts kept in sync (act_…); null: every one, new ones included.
attentionarray of objectsRequired
Campaigns that wait or failed, newest first (at most 20): only of ad accounts that are on and in the setting's choice, and still in Meta's structure.
attention[].adAccountIdstringRequired
act_…
attention[].adAccountNamestring or null
The ad account's name; null when unknown.
attention[].campaignIdstringRequired
The platform's campaign ID.
attention[].launchIdstring (uuid) or null
Its launch, when it has one.
attention[].namestringRequired
Name.
attention[].reasonstring or null
In words.
attention[].reasonCodestring
A registered reason's stable code (such as meta_not_found_campaign), for an app to say it in its language; absent for a reason without one.
attention[].reasonParamsobject
The values reasonCode's sentence names, present exactly when it is.
attention[].statestringRequired
Why it isn't in sync.One of waiting, failed
attention[].updatedAtstring (date-time)
Since.
campaignsintegerRequired
Campaigns kept in sync as launches.
connectedbooleanRequired
Whether the platform is connected.
enabledbooleanRequired
Whether campaigns that aren't archived or deleted are kept in Pluto as launches.
failedintegerRequired
Campaigns that couldn't be synced; tried again later.
lastSyncedAtstring (date-time) or nullRequired
When a campaign was last brought in line.
platformstringRequired
meta.
progressobject or nullRequired
The run in progress: jobId, total and done campaigns.
statusstringRequired
How it's doing: needs_attention when campaigns wait or failed.One of off, not_connected, syncing, up_to_date, needs_attention
versionintegerRequired
Version; 0 until first changed.
waitingintegerRequired
Campaigns waiting because their launch has unpublished changes or is publishing.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Keep in sync doesn't mirror this platform.
  • 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/mirrors/59a4cf9d-a07f-4bfd-9d81-e8712666cabf" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/mirrors/{platform}

Change Keep in sync

Turns Keep in sync on or off, or chooses its ad accounts; absent fields stay. Turning it on, or adding ad accounts, starts a sync at once; turning it off stops the run in progress, and launches already synced stay. 422 for an ad account the connection doesn't have.

Permission: adminCommand: send Idempotency-Key

Parameters

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

adAccountIdsarray of strings or null
The ad accounts to keep in sync (act_…); null for every one, new ones included.
enabledboolean
Keep campaigns that aren't archived or deleted in Pluto (true) or stop (false).

Response200 OK

adAccountIdsarray of strings or nullRequired
The ad accounts kept in sync (act_…); null: every one, new ones included.
attentionarray of objectsRequired
Campaigns that wait or failed, newest first (at most 20): only of ad accounts that are on and in the setting's choice, and still in Meta's structure.
attention[].adAccountIdstringRequired
act_…
attention[].adAccountNamestring or null
The ad account's name; null when unknown.
attention[].campaignIdstringRequired
The platform's campaign ID.
attention[].launchIdstring (uuid) or null
Its launch, when it has one.
attention[].namestringRequired
Name.
attention[].reasonstring or null
In words.
attention[].reasonCodestring
A registered reason's stable code (such as meta_not_found_campaign), for an app to say it in its language; absent for a reason without one.
attention[].reasonParamsobject
The values reasonCode's sentence names, present exactly when it is.
attention[].statestringRequired
Why it isn't in sync.One of waiting, failed
attention[].updatedAtstring (date-time)
Since.
campaignsintegerRequired
Campaigns kept in sync as launches.
connectedbooleanRequired
Whether the platform is connected.
enabledbooleanRequired
Whether campaigns that aren't archived or deleted are kept in Pluto as launches.
failedintegerRequired
Campaigns that couldn't be synced; tried again later.
lastSyncedAtstring (date-time) or nullRequired
When a campaign was last brought in line.
platformstringRequired
meta.
progressobject or nullRequired
The run in progress: jobId, total and done campaigns.
statusstringRequired
How it's doing: needs_attention when campaigns wait or failed.One of off, not_connected, syncing, up_to_date, needs_attention
versionintegerRequired
Version; 0 until first changed.
waitingintegerRequired
Campaigns waiting because their launch has unpublished changes or is publishing.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Pluto doesn't connect this platform.
  • 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/mirrors/59a4cf9d-a07f-4bfd-9d81-e8712666cabf" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: d219a494-76db-42cb-835d-78c73e531d10" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountIds": [
      "act_741877585619437"
    ],
    "enabled": true
  }'