API reference

Ads

Search, edit and move ads, and control live ones.

GET/ads

Search ads across launches

Ads in every unarchived launch, newest first (order=oldest: oldest first). A server-queried collection that pages; q matches names literally.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
labelIdquerystringOptionalCarrying this label.
statusIdquerystringOptionalIn this review status.
assigneeIdquerystringOptionalAssigned to this member.
mediaIdquerystringOptionalWhose creative is this media item.
qquerystringOptionalName contains.
launchIdquerystringOptionalOnly this launch's ads.
adSetIdquerystringOptionalOnly this ad set's ads.
orderquerystringOptionalnewest (default) or oldest: the order the ads were made in.
afterquerystringOptionalCursor.
limitquerystringOptional1-200 (default 50).
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
Ads.
items[].adSetIdstring (uuid) or null
items[].assigneeIdstring (uuid) or null
items[].createdAtstring (date-time)
When the ad was made in Pluto.
items[].idstring (uuid)Required
Ad.
items[].launchIdstring (uuid)Required
Launch.
items[].launchNamestring
Launch name.
items[].launchStatusstring
Launch status.
items[].mediaIdstring (uuid) or null
items[].namestringRequired
Name.
items[].statusIdstring (uuid) or null
items[].versioninteger
The ad's version: send it as expectedVersion to change the ad.
nextAfterstring (uuid) or null

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/ads" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/ads/bulk/apply

Apply a previewed bulk edit of ads

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

operationsarray of objectsRequired
The previewed operations.
snapshotTokenstringRequired
From the preview.

Response200 OK

Applied count, conflicts and the changeset ID. Applied in chunks by the job jobId; pending counts items a worker was still applying when the request stopped waiting.

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 POST "$PLUTO_API/ads/bulk/apply" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 1630a08d-f2a3-46af-89cc-e49c7d5a92f4" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {}
    ],
    "snapshotToken": "hPu4lXSXE27KMmF240dvBsz6amLEuPSGYLiWnzJy"
  }'
POST/ads/bulk/preview

Preview a bulk edit of ads

Permission: write

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.

Request body

operationsarray of objectsRequired
Operations.
selectorobjectRequired
Filters or explicit ids.

Response200 OK

affectedintegerRequired
Items the selector matched (the snapshot).
approvalResetsintegerRequired
Approved ads whose reviewed content changes, so they return to review.
changedintegerRequired
Items the operations change.
entitystringRequired
What the edit changes.One of ad, ad_set
expiresAtstring (date-time)Required
The snapshot token expires then.
problemsarray of objectsRequired
Every item that would be rejected, with the reason.
problems[].idstring (uuid)Required
Item.
problems[].messagestringRequired
Why it can't be changed.
publishedintegerRequired
Items already created at a provider: their change becomes a pending revision to publish.
rejectedintegerRequired
Items the operations can't apply to (see problems).
samplesarray of objectsRequired
Before/after of the first changed items.
samples[].afterobjectRequired
Changed fields after.
samples[].approvalResetbooleanRequired
Returns to review.
samples[].beforeobjectRequired
Changed fields before.
samples[].idstring (uuid)Required
Item.
samples[].namestringRequired
Name.
samples[].publishedbooleanRequired
Becomes a pending revision.
snapshotTokenstring (uuid)Required
Pass to apply; pins the resolved item set.
unchangedintegerRequired
Items already as the operations ask.

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 -X POST "$PLUTO_API/ads/bulk/preview" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {}
    ],
    "selector": {}
  }'
POST/ads/move

Move ads

Move ads to an ad set, or to another launch.

With launchId, draft ads move to that launch with their comments, activity, labels and followers, keeping what they show. Published ads can't move (409).

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

adIdsarray of strings (uuid)
Ads.
adSetIdstring (uuid) or nullRequired
adsarray of objects
Ads with versions.
beforeIdstring (uuid) or null
launchIdstring (uuid)
Destination launch; the ad set must be in it.

Response200 OK

Moved ads.

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 POST "$PLUTO_API/ads/move" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 59ac3526-25e6-4808-b27a-e79d13e8ef48" \
  -H "Content-Type: application/json" \
  -d '{
    "adIds": [
      "a96d7456-dc02-4734-998b-3e439361abe3"
    ],
    "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
    "ads": [
      {}
    ],
    "beforeId": "2d6da6a4-f1d1-47c6-a1f6-3a3b32c6e8b7",
    "launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560"
  }'
PATCH/ads/{id}

Update an ad

Name, ad set, creative, review status, assignee, labels and setting overrides. Changing only statusId (approving or requesting changes) needs just the review permission.

Permission: writeCommand: send Idempotency-Key

Parameters

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

adSetIdstring (uuid) or null
assigneeIdstring (uuid) or null
editobject
An edit in effective values (copy, CTA, URL, identity, creative settings), applied after overrides. Values the editor never offers (a call to action off the list, an enhancement the format lacks) are a 422.
edit.bestCardsFirstboolean
A carousel shows its best-performing cards first (default true). Meta only.
edit.cardsarray of objects
A carousel ad's cards, all of them in order (2 to 10); replaces the ad's cards. On Meta an ad with cards is a carousel (each card an image or video; the ad's call to action goes on every card, its URL is the "See more" link and the link of a card without its own). On platforms that set the format per ad set, only an ad set whose format is a carousel takes them.
edit.cards[].descriptionstring
The card's description, where the platform shows one.
edit.cards[].headlinestring
The card's headline.
edit.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
edit.cards[].urlstring
The page the card opens (https://…).
edit.creativeobject
Creative settings.
edit.creative.catalogItemsboolean
Show products from your catalog.
edit.creative.featuresobject
Advantage+ creative enhancements per format (each is opt-in).
edit.creative.features.carouselobject
Carousel ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
edit.creative.features.imageobject
Image ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
edit.creative.features.videoobject
Video ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
edit.creative.multiAdvertiserboolean
Multi-advertiser ads.
edit.creative.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
edit.creative.productSetIdstring
Catalog product set: its numeric Meta ID.
edit.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
edit.descriptionstring
Description.
edit.displayLinkstring
Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
edit.endCardboolean
A carousel ends with a card showing the Page (default true). Meta only.
edit.headlinestring
Headline.
edit.identityobject
The Page and Instagram account the ad publishes as.
edit.identity.instagramstring
Instagram account: its Meta ID; usually the one linked to the Page.
edit.identity.pagestring
Facebook Page: its numeric Meta ID (get_meta_integration).
edit.imageCropsobject
An image ad's own crop per shape, in the image's pixels (get_media gives its width and height): 1:1 for every placement outside the groups, 4:5 for Feeds, 9:16 for Stories and Reels, 1.91:1 for right column and search. Each box stays inside the image with its shape's proportions, to the pixel. Shapes left out keep theirs; null puts one back in the middle. A box makes the ad crop (creative.placementCrops center). A new image drops the ad's crops.
edit.imageCrops.1.91:1object or null
edit.imageCrops.1.91:1.heightintegerRequired
edit.imageCrops.1.91:1.widthintegerRequired
edit.imageCrops.1.91:1.xintegerRequired
Left edge, in pixels from the image's left.
edit.imageCrops.1.91:1.yintegerRequired
Top edge, in pixels from the image's top.
edit.imageCrops.1:1object or null
edit.imageCrops.1:1.heightintegerRequired
edit.imageCrops.1:1.widthintegerRequired
edit.imageCrops.1:1.xintegerRequired
Left edge, in pixels from the image's left.
edit.imageCrops.1:1.yintegerRequired
Top edge, in pixels from the image's top.
edit.imageCrops.4:5object or null
edit.imageCrops.4:5.heightintegerRequired
edit.imageCrops.4:5.widthintegerRequired
edit.imageCrops.4:5.xintegerRequired
Left edge, in pixels from the image's left.
edit.imageCrops.4:5.yintegerRequired
Top edge, in pixels from the image's top.
edit.imageCrops.9:16object or null
edit.imageCrops.9:16.heightintegerRequired
edit.imageCrops.9:16.widthintegerRequired
edit.imageCrops.9:16.xintegerRequired
Left edge, in pixels from the image's left.
edit.imageCrops.9:16.yintegerRequired
Top edge, in pixels from the image's top.
edit.placementMediaobject
Another image or video (a media library ID) for a group of placements, Meta only: feeds (Facebook and Instagram feeds, profile feeds, Explore home, Threads; 4:5), stories (Stories and Reels; 9:16), rightColumn (right column and search results; 1.91:1). The ad's own file shows everywhere else. An image ad takes images and a video ad videos (Meta takes one kind per ad); never a carousel. Groups left out keep theirs; null removes one.
edit.placementMedia.feedsstring (uuid) or null
edit.placementMedia.rightColumnstring (uuid) or null
edit.placementMedia.storiesstring (uuid) or null
edit.textstring
Primary text.
edit.urlstring
Website URL the ad links to (https://…).
edit.useLauncharray of strings
Follow the launch again for these groups, before the rest of the edit: copy (text, headline, description), destination (CTA, URL, the ad's own URL parameters and display link), identity (Page and Instagram), creativeSettings (enhancements, multi-advertiser, catalog, placementCrops).
edit.utmstring
Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's utm value follows the launch again, "" sends none.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
labelIdsarray of strings (uuid)
Replace all labels.
labelsobject
add / remove label IDs.
mediaIdstring (uuid)
Creative: an image or a video; the ad's format follows it. On a live ad the change is a revision that publishes a new creative, which Meta reviews again.
namestring
Name.
overridesobject
Replaces the stored overrides (values equal to the launch's collapse to inherit). An unknown key is a 422 naming it (overrides.<key>).
overrides.bestCardsFirstboolean
false when a carousel keeps its card order (default true). Meta only.
overrides.cardsarray of objects
A carousel ad's cards, in order.
overrides.cards[].descriptionstring
The card's description, where the platform shows one.
overrides.cards[].headlinestring
The card's headline.
overrides.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
overrides.cards[].urlstring
The page the card opens (https://…).
overrides.copyVariationsobject
Copy lists this ad changes; a list left out follows the launch.
overrides.copyVariations.descriptionsarray of strings
Description; publishing sends one.
overrides.copyVariations.headlinesarray of strings
Headline; publishing sends one.
overrides.copyVariations.primaryTextsarray of strings
Primary text; publishing sends one.
overrides.creativeSettingsobject
Creative settings this ad changes.
overrides.creativeSettings.catalogItemsboolean
Catalog items.
overrides.creativeSettings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
overrides.creativeSettings.creative.carouselarray of strings
Carousel ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
overrides.creativeSettings.creative.imagearray of strings
Image ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
overrides.creativeSettings.creative.videoarray of strings
Video ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
overrides.creativeSettings.multiAdvertiserboolean
Multi-advertiser ads.
overrides.creativeSettings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
overrides.creativeSettings.productSetIdstring
Product set ID.
overrides.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
overrides.endCardboolean
false when a carousel has no end card (default true). Meta only.
overrides.identityobject or null
Page and Instagram account IDs; null follows the launch.
overrides.identity.instagramstring
overrides.identity.pagestring
overrides.imageCropsobject
The ad's own crop per shape, in its image's pixels; shapes left out are cropped in the middle while the ad crops.
overrides.imageCrops.1.91:1object
overrides.imageCrops.1.91:1.heightintegerRequired
overrides.imageCrops.1.91:1.widthintegerRequired
overrides.imageCrops.1.91:1.xintegerRequired
Left edge, in pixels from the image's left.
overrides.imageCrops.1.91:1.yintegerRequired
Top edge, in pixels from the image's top.
overrides.imageCrops.1:1object
overrides.imageCrops.1:1.heightintegerRequired
overrides.imageCrops.1:1.widthintegerRequired
overrides.imageCrops.1:1.xintegerRequired
Left edge, in pixels from the image's left.
overrides.imageCrops.1:1.yintegerRequired
Top edge, in pixels from the image's top.
overrides.imageCrops.4:5object
overrides.imageCrops.4:5.heightintegerRequired
overrides.imageCrops.4:5.widthintegerRequired
overrides.imageCrops.4:5.xintegerRequired
Left edge, in pixels from the image's left.
overrides.imageCrops.4:5.yintegerRequired
Top edge, in pixels from the image's top.
overrides.imageCrops.9:16object
overrides.imageCrops.9:16.heightintegerRequired
overrides.imageCrops.9:16.widthintegerRequired
overrides.imageCrops.9:16.xintegerRequired
Left edge, in pixels from the image's left.
overrides.imageCrops.9:16.yintegerRequired
Top edge, in pixels from the image's top.
overrides.placementMediaobject
Another image or video per group of placements (feeds, stories, rightColumn), by media library ID; the ad's own file shows everywhere else.
overrides.placementMedia.feedsstring (uuid)
overrides.placementMedia.rightColumnstring (uuid)
overrides.placementMedia.storiesstring (uuid)
overrides.urlstring
Website URL.
overridesPatchobject
An RFC 7396 merge patch of the stored overrides: changes only the keys it names (null follows the launch again), so edits to different fields by different people both apply. Send either overrides or overridesPatch. An unknown key is a 422 naming it (overridesPatch.<key>).
statusIdstring (uuid)
Review status.

Response200 OK

adSetIdstring (uuid) or null
Ad set; null is ungrouped.
assigneeIdstring (uuid) or null
Assignee.
createdAtstring (date-time)
Created.
creativeLinkIdstring (uuid) or null
Shared with the ads copied from or to it in its launch group's other campaigns (GET /ads/{id}/linked).
cropsobject
Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
effectiveobject
The content the ad publishes: overrides, otherwise the launch's values.
externalKeystring or null
Your own key.
formatstring
Creative format: audio is an audio ad, where the platform has them; text is an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One of image, video, carousel, audio, text
idstring (uuid)Required
ID.
issuesarray of strings
Problems with the effective content.
labelIdsarray of strings (uuid)
Labels.
launchIdstring (uuid)
Launch.
mediaIdstring (uuid) or null
Creative.
namestring
Name.
overridesobject
Only what this ad changes.
positioninteger
Order.
statusIdstring (uuid) or null
Review status.
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 7d0690f6-4cab-4f2a-80c2-804691bbbb67" \
  -H "Content-Type: application/json" \
  -d '{
    "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
    "assigneeId": "1ad53f36-b81b-4e8f-9231-32950ee3d9e2",
    "edit": {
      "bestCardsFirst": true,
      "cards": [
        {
          "description": "Two drops every morning for brighter, even skin.",
          "headline": "Brighter skin in 14 days",
          "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
          "url": "https://brevanne.com/products/vitamin-c-serum"
        }
      ],
      "creative": {
        "catalogItems": true,
        "features": {
          "carousel": {
            "description_automation": true,
            "enhance_cta": true,
            "inline_comment": true,
            "profile_card": true,
            "site_extensions": true,
            "text_optimizations": true,
            "text_translation": true
          },
          "image": {
            "adapt_to_placement": true,
            "enhance_cta": true,
            "image_animation": true,
            "image_background_gen": true,
            "image_brightness_and_contrast": true,
            "image_templates": true,
            "image_touchups": true,
            "image_uncrop": true,
            "inline_comment": true,
            "music": true,
            "site_extensions": true,
            "text_optimizations": true,
            "text_translation": true
          },
          "video": {
            "enhance_cta": true,
            "inline_comment": true,
            "site_extensions": true,
            "text_optimizations": true,
            "text_translation": true,
            "video_auto_crop": true,
            "video_filtering": true,
            "video_uncrop": true
          }
        },
        "multiAdvertiser": true,
        "placementCrops": "off",
        "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
      },
      "cta": "Apply now",
      "description": "Two drops every morning for brighter, even skin.",
      "displayLink": "Brevanne",
      "endCard": true,
      "headline": "Brighter skin in 14 days",
      "identity": {
        "instagram": "Brevanne",
        "page": "Brevanne"
      },
      "imageCrops": {
        "1.91:1": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "1:1": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "4:5": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "9:16": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        }
      },
      "placementMedia": {
        "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
        "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
        "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
      },
      "text": "Can we try the 4x5 cut for Instagram feed before we publish?",
      "url": "https://brevanne.com/products/vitamin-c-serum",
      "useLaunch": [
        "copy"
      ],
      "utm": "https://brevanne.com/products/vitamin-c-serum"
    },
    "expectedVersion": 3,
    "labelIds": [
      "3b3e38bc-b355-4d75-a044-270c99d48ced"
    ],
    "labels": {},
    "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
    "name": "Vitamin C Serum, UGC 9x16",
    "overrides": {
      "bestCardsFirst": true,
      "cards": [
        {
          "description": "Two drops every morning for brighter, even skin.",
          "headline": "Brighter skin in 14 days",
          "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
          "url": "https://brevanne.com/products/vitamin-c-serum"
        }
      ],
      "copyVariations": {
        "descriptions": [
          "Two drops every morning for brighter, even skin."
        ],
        "headlines": [
          "Brighter skin in 14 days"
        ],
        "primaryTexts": [
          "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
        ]
      },
      "creativeSettings": {
        "catalogItems": true,
        "creative": {
          "carousel": [
            "text_optimizations"
          ],
          "image": [
            "text_optimizations"
          ],
          "video": [
            "text_optimizations"
          ]
        },
        "multiAdvertiser": true,
        "placementCrops": "off",
        "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
      },
      "cta": "Apply now",
      "endCard": true,
      "identity": {
        "instagram": "Brevanne",
        "page": "Brevanne"
      },
      "imageCrops": {
        "1.91:1": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "1:1": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "4:5": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        },
        "9:16": {
          "height": 1920,
          "width": 1080,
          "x": 3,
          "y": 3
        }
      },
      "placementMedia": {
        "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
        "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
        "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
      },
      "url": "https://brevanne.com/products/vitamin-c-serum"
    },
    "overridesPatch": {},
    "statusId": "069ff91e-35e1-4603-afc3-792b04f09624"
  }'
DELETE/ads/{id}

Delete an ad

An ad with comments or activity, or one deleted at its platform (e.g. in its ads manager), is archived instead (archived: true): it leaves the board, keeps its conversation and can be restored (POST /ads/{id}/restore). 409 while the ad is live on its ad platform: pause it, or delete it there (POST /ads/{id}/platform-delete).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe ad's ID.
expectedVersionquerystringOptionalVersion.
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

id, deleted, and archived: true when it was archived.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: fbb3f456-b22f-477f-8cde-4a864cfee3bf"
POST/ads/{id}/copies

Duplicate a launch's live ad

A launch's live object by its Pluto ID, copied on the launch's platform: in Meta with Meta's copies (intoAdSetId / intoCampaignId take Meta IDs there); on another platform Pluto reads each object and creates it again: in another ad set or campaign of the same ad account where the platform's own Copy and paste does that (intoAdSetId / intoCampaignId: its IDs, or Pluto IDs of what a launch published), otherwise in the same parent (intoAdSetId and intoCampaignId are refused). Copies start paused unless statusOption says otherwise; deepCopy copies what is inside too. Answers 202 with the job; its items name each copy (output.copiedId), written into the synced lists as soon as it exists and into change history with who asked.

Permission: publishCommand: send Idempotency-Key

Parameters

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

deepCopyboolean
Ad sets and campaigns: copy what is inside too (default false).
endTimestring (date-time)
Ad sets and campaigns: when the copied ad sets end.
intoAdSetIdstring
Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignIdstring
Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsobject
renameOptions.prefixstring
Put before the name.
renameOptions.strategystring
Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of ONLY_TOP_LEVEL_RENAME, DEEP_RENAME, NO_RENAME
renameOptions.suffixstring
Put after the name (Meta's default is a localized " - Copy").
startTimestring (date-time)
Ad sets and campaigns: when the copied ad sets start.
statusOptionstring
How the copy starts (default PAUSED).One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Response202 Accepted

jobIdstring (uuid)Required
The copy job; its items name each copy (output.copiedId).
levelstringRequired
What is copied.One of campaign, ad_set, ad
objectsintegerRequired
How many objects the job copies.
sourceIdstringRequired
The original's ID on its platform.
statusOptionstringRequired
How the copies start.One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/copies" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 357eb8cd-c214-4359-9778-813c2e069dce" \
  -H "Content-Type: application/json" \
  -d '{
    "deepCopy": true,
    "endTime": "2026-09-30T13:00:00Z",
    "intoAdSetId": "120240541407845332",
    "intoCampaignId": "120227168091908311",
    "renameOptions": {
      "prefix": "Fall - ",
      "strategy": "ONLY_TOP_LEVEL_RENAME",
      "suffix": " - Copy"
    },
    "startTime": "2026-09-30T13:00:00Z",
    "statusOption": "PAUSED"
  }'
POST/ads/{id}/duplicate

Duplicate an ad

A copy right after the original, back at the default review status.

Permission: writeCommand: send Idempotency-Key

Parameters

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

asDraftedboolean
A new draft ad from the ad as drafted, carrying changes Meta won't make on the live ad, even for an ad that came from Meta (409 when it holds a value managed in Meta).

Response201 Created

adSetIdstring (uuid) or null
Ad set; null is ungrouped.
assigneeIdstring (uuid) or null
Assignee.
createdAtstring (date-time)
Created.
creativeLinkIdstring (uuid) or null
Shared with the ads copied from or to it in its launch group's other campaigns (GET /ads/{id}/linked).
cropsobject
Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
effectiveobject
The content the ad publishes: overrides, otherwise the launch's values.
externalKeystring or null
Your own key.
formatstring
Creative format: audio is an audio ad, where the platform has them; text is an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One of image, video, carousel, audio, text
idstring (uuid)Required
ID.
issuesarray of strings
Problems with the effective content.
labelIdsarray of strings (uuid)
Labels.
launchIdstring (uuid)
Launch.
mediaIdstring (uuid) or null
Creative.
namestring
Name.
overridesobject
Only what this ad changes.
positioninteger
Order.
statusIdstring (uuid) or null
Review status.
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/duplicate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 8e5c911f-2b4c-4248-95f2-ac72022810f4" \
  -H "Content-Type: application/json" \
  -d '{
    "asDrafted": true
  }'
GET/ads/{id}/linked

List linked ads

The ads linked to this one in its launch group's other campaigns (copied from or to it): each with its campaign's label, platform and ad account, whether it's live, whether it's still identical (same file, text, headline and URL), and what its platform no longer lets change now that it's live (frozen). Guests get none.

Permission: readGuests too

Parameters

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

creativeLinkIdstring (uuid) or nullRequired
The link they share; null when the ad has none.
itemsarray of objectsRequired
Linked ads.
items[].adAccountIdstring or null
Its ad account.
items[].adIdstring (uuid)Required
The linked ad.
items[].frozenarray of objectsRequired
What its platform no longer lets change.
items[].frozen[].fieldstringRequired
text, headline, description, url or media.
items[].frozen[].messagestringRequired
Why it can't change.
items[].identicalbooleanRequired
Same file, text, headline and URL.
items[].labelstringRequired
Its campaign's name in the launch group.
items[].launchIdstring (uuid)Required
Its campaign (a launch).
items[].livebooleanRequired
It published.
items[].namestringRequired
The ad's name.
items[].platformstringRequired
Its platform.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/linked" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/ads/{id}/linked/update

Update linked ads

Carries this ad's text, headline, description, URL or media over to its linked ads (all, or adIds), each through its own platform's rules: review starts again where reviewed content changes, and a published campaign gets pending changes. What a platform doesn't show, or freezes once an ad is live, is skipped with the reason. Never automatic.

Permission: writeCommand: send Idempotency-Key

Parameters

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

adIdsarray of strings (uuid)
Only these linked ads (default all).
fieldsarray of strings
What to carry over (default all).

Response200 OK

itemsarray of objectsRequired
One per linked ad.
items[].adIdstring (uuid)Required
The linked ad.
items[].appliedarray of stringsRequired
What was carried over.
items[].errorsarray of objects
Why it failed, in its platform's words.
items[].errors[].fieldstringRequired
Field.
items[].errors[].messagestringRequired
Why.
items[].platformstringRequired
Its platform.
items[].skippedarray of objectsRequired
What was left out.
items[].skipped[].fieldstringRequired
Field.
items[].skipped[].reasonstringRequired
Why.
items[].statusstringRequired
What happened.One of updated, skipped, failed

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/linked/update" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 506c0038-e3ea-4ca8-a78d-b9484f9c4a08" \
  -H "Content-Type: application/json" \
  -d '{
    "adIds": [
      "a96d7456-dc02-4734-998b-3e439361abe3"
    ],
    "fields": [
      "text"
    ]
  }'
POST/ads/{id}/meta-delete

Delete a live ad (first route)

Irreversible. The same as POST /ads/{id}/platform-delete, under its first name: deletes the ad on its ad platform (in Meta status=DELETED), reads it back as deleted and then archives it in the launch (history kept; GET /launches/{id}/archived). A live ad can't be deleted from the draft otherwise; pausing is the reversible alternative.

Permission: publishCommand: send Idempotency-Key

Parameters

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

expectedVersioninteger
Optional: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted on the ad platform.
jobIdstring (uuid)Required
The job deleting on the ad platform.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-delete" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: ddfaf642-8b7f-4ee5-a5ca-df13897362fe" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'
POST/ads/{id}/meta-move

Move a live ad in Meta

Meta can't move a live ad. After the ad's draft moved to another live ad set of the launch (listed under moves in GET /launches/{id}/revisions), this copies the ad into that ad set in Meta (POST /{ad_id}/copies, new IDs), links the copy as a new ad there and puts the original's draft back where it is live. The copy starts paused and is turned on only with activateCopy. original: pause pauses the original after the copy exists; keep leaves it as it is. Keeping a delivering original while turning the copy on is refused (409 bothDeliver) unless confirmBothDeliver is true, since both would deliver. A retry never copies twice. Discarding the pending adSetId change instead puts the draft back. Meta launches only: another platform's live ad stays in the ad set it was published in (POST /ads/{id}/copies copies it there).

Permission: publishCommand: send Idempotency-Key

Parameters

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

activateCopyboolean
Turn the copy on once it exists (default false: it stays paused).
confirmBothDeliverboolean
Confirms that the original and the copy both deliver.
expectedVersioninteger
The ad's draft version you reviewed.
originalstringRequired
What happens to the original once the copy exists.One of pause, keep

Response202 Accepted

jobId, the move (entity, id, name, providerId, from, to, originalDelivers), original, activateCopy, bothDeliver and budget (null for ads).

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Not a pending move, not ready (reason), or both would deliver without confirmBothDeliver.
  • 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-move" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: fb80c766-5415-463d-a4b4-fa3671ad455a" \
  -H "Content-Type: application/json" \
  -d '{
    "activateCopy": true,
    "confirmBothDeliver": true,
    "expectedVersion": 3,
    "original": "pause"
  }'
GET/ads/{id}/meta-preview

Get Meta's preview of an ad

Meta's preview of an ad in one placement.

Meta renders the ad as it would show in the placement and answers an iframe URL (src, on www.facebook.com, never Meta's HTML) with the size Meta drew it at; show it sandboxed. source: ad previews the live ad in Meta; source: draft previews the ad's current values (a draft, or edits not published yet), built like publishing builds the creative. Cached for 10 minutes per ad version and placement; ask again after expiresAt. 409 not_previewable with missing (ad_account, page, url, media, media_processing, video_not_uploaded, format, meta_ad, meta_refused) when Meta can't draw it yet (a video must be uploaded to the ad account by publishing first); 409 meta_disconnected, meta_reauthorize or meta_permissions for the Meta connection; 429 when Meta or the workspace's preview budget (30 Meta calls per 5 minutes) is exhausted. Ads of Meta launches only.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe ad's ID.
placementquerystringOptionalfacebook_feed, instagram_feed, facebook_story, instagram_story, facebook_reels, instagram_reels or instagram_explore (INSTAGRAM_EXPLORE_GRID_HOME).
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

adFormatstringRequired
Meta's ad_format, e.g. INSTAGRAM_STANDARD.
adVersionintegerRequired
The ad version the preview shows.
expiresAtstring (date-time)Required
Ask again after this.
fetchedAtstring (date-time)Required
When Meta drew it.
heightintegerRequired
Iframe height Meta drew, in pixels.
placementstringRequired
The placement.One of facebook_feed, instagram_feed, facebook_story, instagram_story, facebook_reels, instagram_reels, instagram_explore, facebook_marketplace, facebook_right_column, facebook_instream, instagram_search
sourcestringRequired
ad: the live ad in Meta; draft: the ad's current values.One of ad, draft
srcstringRequired
Meta's preview iframe URL.
widthintegerRequired
Iframe width Meta drew, in pixels.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Not previewable yet (details.missing), or the Meta connection needs attention.
  • 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-preview" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/ads/{id}/platform-delete

Delete a live ad

Irreversible. Deletes a launch's live ad on its ad platform and reads it back as deleted, then archives it in the launch (history kept; GET /launches/{id}/archived). In Meta the same as POST /ads/{id}/meta-delete; on a platform that deletes only drafts outright, anything that ran is set to pending deletion (stopped for good). Pausing is the reversible alternative.

Permission: publishCommand: send Idempotency-Key

Parameters

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

expectedVersioninteger
Optional: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted on the ad platform.
jobIdstring (uuid)Required
The job deleting on the ad platform.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-delete" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5b065b85-0415-427d-86b6-a44747316230" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'
GET/ads/{id}/platform-settings

Get an ad's platform settings

What the launch's platform keeps per ad beyond its text, link and file, in the fields of the platform's launch settings at the ad level (GET /platforms/{platform}/spec). An ad inherits the launch's platformSettings.ad and stores only the keys it changes. A platform that keeps nothing per ad answers 422.

Permission: read

Parameters

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

adIdstringRequired
The ad.
launchIdstringRequired
Its launch.
ownobjectRequired
Only the keys this ad changes.
platformstringRequired
The launch's platform.
settingsobjectRequired
The ad's effective platform settings: the launch's platformSettings.ad with the ad's own keys.
versionintegerRequired
The version to send as expectedVersion; 0 while the ad has no keys of its own.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such ad.
  • 422The launch's platform keeps no settings per ad.
  • 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-settings" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/ads/{id}/platform-settings

Change an ad's platform settings

Sets the named keys of the ad's own platform settings; null goes back to the launch's value. Each key is checked by the platform's rules against the ad's own text: a value that doesn't fit is refused with 422 in the platform's words, on its field. Send expectedVersion from the last read; another change in between answers 409 with the current settings.

Permission: writeCommand: send Idempotency-Key

Parameters

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

expectedVersioninteger
The version last read.
settingsobjectRequired
The keys to set; null removes a key.

Response200 OK

adIdstringRequired
The ad.
launchIdstringRequired
Its launch.
ownobjectRequired
Only the keys this ad changes.
platformstringRequired
The launch's platform.
settingsobjectRequired
The ad's effective platform settings: the launch's platformSettings.ad with the ad's own keys.
versionintegerRequired
The version to send as expectedVersion; 0 while the ad has no keys of its own.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such ad.
  • 409The ad's settings changed since expectedVersion (the body carries current), or the launch is being published.
  • 422A value doesn't fit, or the launch's platform keeps no settings per ad.
  • 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-settings" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 92b5c018-9725-40b8-a268-d52fea584636" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "settings": {}
  }'
POST/ads/{id}/restore

Restore an archived ad as a draft

Never published: the same ad returns to the board with its conversation (into its ad set when that is still there). Deleted at its ad platform: a new draft copy is created and the original stays archived with its results. 409 when it isn't archived, a newer version exists, or its name or spec key is taken.

Permission: writeCommand: send Idempotency-Key

Parameters

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

expectedVersioninteger
Optional: the archived version seen.

Response200 OK

adIdsarray of strings (uuid)Required
Ads restored with an ad set.
copybooleanRequired
A new draft copy (the original was deleted at its ad platform and stays archived).
entitystringRequired
What was restored.One of ad, ad_set
idstring (uuid)Required
The draft now on the board: the same ID, or the copy's.
launchIdstring (uuid)Required
Launch.
restoredFromstring (uuid)Required
The archived ad or ad set.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/restore" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 54e51790-ce71-4e08-9a8b-052eddc3e245" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'
POST/ads/{id}/status

Pause or activate an ad

Permission: publishCommand: send Idempotency-Key

Parameters

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

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or on Meta when its limit of 4 budget changes per ad set per hour allows.
jobIdstring (uuid)Required
The job applying the change.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/status" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 2acfad23-e889-4e0c-9bf9-510eb956359c" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE"
  }'
POST/ads/{id}/unlink

Remove an ad link

Takes the ad out of its link; the others stay linked.

Permission: writeCommand: send Idempotency-Key

Parameters

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

creativeLinkIdstring (uuid) or nullRequired
The link they share; null when the ad has none.
itemsarray of objectsRequired
Linked ads.
items[].adAccountIdstring or null
Its ad account.
items[].adIdstring (uuid)Required
The linked ad.
items[].frozenarray of objectsRequired
What its platform no longer lets change.
items[].frozen[].fieldstringRequired
text, headline, description, url or media.
items[].frozen[].messagestringRequired
Why it can't change.
items[].identicalbooleanRequired
Same file, text, headline and URL.
items[].labelstringRequired
Its campaign's name in the launch group.
items[].launchIdstring (uuid)Required
Its campaign (a launch).
items[].livebooleanRequired
It published.
items[].namestringRequired
The ad's name.
items[].platformstringRequired
Its platform.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/unlink" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 44be0077-e30f-4fb5-bab9-6bbf38216241"
GET/ads/{id}/view

Get what a model sees of an ad

The ad's creative as stills sized for vision models (an image's still, or a video's frames with their timestamps) behind short-lived URLs, with the copy it runs with and, once published on Meta, its Meta ad ID and delivery status. The first view of a video may wait a few seconds while its frames are taken.

Permission: readGuests too

Parameters

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

adAccountIdstring or null
The ad account's ID on its platform (act_… on Meta).
adSetIdstring (uuid) or null
Ad set.
aspectRatiostring or null
As ad specs name it.
copyobject or nullRequired
The copy it runs with: primaryText, headline, description, callToAction, url; a launch ad adds its variations (primaryTexts, headlines, descriptions).
durationMsinteger or null
Videos: duration.
effectiveStatusstring or null
Delivery in Meta when it's live there.
expiresAtstring (date-time)Required
When the still URLs stop working.
formatstring or null
image, video or audio (an audio ad, where the platform has them).
hasAudioboolean or null
Videos: whether there is a sound track.
idstringRequired
The Pluto ad ID, or the Meta ad ID.
launchIdstring (uuid) or null
Launch.
mediaobject or null
A launch ad's creative.
media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
media.byteSizeinteger
Size in bytes.
media.contentTypestring
MIME type.
media.createdAtstring (date-time)
Added.
media.createdBystring (uuid)
Their ID.
media.createdByKindstring
Who added it.One of person, api_key, agent, system
media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
media.durationMsinteger or null
Videos and audio files: duration.
media.errorstring or null
Why processing failed.
media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
media.folderIdstring (uuid) or null
Folder; null for the library root.
media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
media.heightinteger or null
Pixels, once processed.
media.idstring (uuid)Required
ID.
media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
media.namestring
Name.
media.pageCountinteger or null
Documents: pages, once processed.
media.processedAtstring (date-time) or null
Processed.
media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
media.sourceUrlstring or null
Where an import came from.
media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
media.updatedAtstring (date-time)
Last change.
media.versioninteger
Increments on every change; send as expectedVersion.
media.warningsarray of objects
Provider-spec findings that don't block use.
media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
media.warnings[].messagestringRequired
Finding.
media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
media.widthinteger or null
Pixels, once processed.
metaAdIdstring or null
The ad in Meta, once published there.
namestringRequired
Name.
notestring or null
Why there's nothing (or less) to look at.
sourcestringRequired
launch: an ad of a Pluto launch (draft or published); meta: an ad that exists only in Meta.One of launch, meta
stillsarray of objectsRequired
In order: one for an image, up to 8 frames for a video.
stills[].atstring or null
Videos: the same as a timestamp, e.g. 0:04.
stills[].atMsinteger or null
Videos: where the frame is (ms).
stills[].heightintegerRequired
Pixels.
stills[].urlstringRequired
Short-lived URL of the JPEG.
stills[].widthintegerRequired
Pixels.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/view" \
  -H "Authorization: Bearer $PLUTO_KEY"