API reference

Competitors

The in-app Agent: chats with streamed answers, approvals for publish and admin actions, metered in the organization's usage (see Billing).

GET/competitors

List researched competitors

The workspace's competitors researched so far, the latest first, with how many of their ads are kept, running and read by Creative Memory. Also in MCP as part of get_competitor_ads.

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

itemsarray of objectsRequired
The workspace's competitors.

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/competitors" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/competitors/ads

List competitors' ads

Researched competitors' ads with what Creative Memory found in them, their funnel stage, angles and why, their Ad Library link and a short-lived address of Pluto's copy of their picture. ids is a comma-separated list; the other filters are get_competitor_ads's. Running ads first, the longest-running first. Also in MCP as get_competitor_ads.

Permission: read

Parameters

NameTypeRequiredDescription
advertiserIdquerystringOptionalA researched competitor.
pageIdquerystringOptionalOr its Facebook Page ID.
advertiserquerystringOptionalOr its name or domain as researched.
idsquerystringOptionalThese ads only, comma-separated, up to 100.
stagequerystringOptionaltop, middle or bottom.
anglequerystringOptionalAn angle the ads show (discount, social_proof, problem, ...).
activequerystringOptionaltrue: running now; false: stopped.
analyzedquerystringOptionaltrue: Creative Memory's findings ready.
minDaysquerystringOptionalRunning at least this many days.
formatquerystringOptionalThe Library's format: image, video, carousel, dco, ...
qquerystringOptionalWords in the copy.
limitquerystringOptionalAds per page, 1-50 (default 20).
afterquerystringOptionalThe previous page's nextAfter.
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

advertisersarray of objects
The workspace's competitors, when none was named.
itemsarray of objectsRequired
This page.
nextAfterstring or integer or null
Pass as the 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/competitors/ads" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/competitors/research

Run competitor research

Finds a competitor's running ads in Meta's public Ad Library by its name, Facebook Page ID or shop's domain in one country, keeps them in the workspace with their images and videos, and has Creative Memory read the main file of the longest-running ones (analyze, default true), charged in the organization's credits as the workspace's own analyses are (50 per image, 250 per started minute of video, its first three minutes) and never ahead of its own files. Answers at once with what's ready; the rest follows in GET /competitors/ads and GET /competitors/{id}/funnel. A site's refusal is answered in library.blocked with the address to open. Also in MCP as research_competitor.

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

advertiserstring
The brand as it advertises (its Facebook Page's name), up to 100 characters.
analyzeboolean
Give their main files to Creative Memory (default true; uses credits).
countrystringRequired
Where its ads run: a two-letter country code (US, DE, GB) or ALL.
domainstring
Its shop's domain (shop.example): found among the sites its ads link to.
maxAdsinteger
Running ads to read, 1-50 (default 30).
maxAnalysesinteger
Ads whose main file Creative Memory reads, the longest-running first, 0-30 (default 10).
pageIdstring
Its numeric Facebook Page ID, when known (from candidates or the Ad Library).

Response200 OK

adsarray of objectsRequired
Its longest-running ads.
advertiserobject or null
The competitor: id, name, pageId, domain, country, libraryUrl (its ads in the public Ad Library), researchedAt, ads, activeAds, analyzedAds.
analysesobjectRequired
Creative Memory: queued (now), inProgress, ready, waiting (for credits or Creative Memory, with reason), failed, maxCredits (the most the queued files use).
candidatesarray of objects
When none matched for sure.
foundbooleanRequired
Whether the advertiser was found.
libraryobject or null
How the Library was read: source (library_site or library_api), url (the public address), shownTotal, blocked (why the site didn't answer; null when it did), ms, cached.
notestringRequired
What the answer is and what comes next.
readintegerRequired
Running ads read now.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402The organization is read-only (only with analyze).
  • 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/competitors/research" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: f40c4944-5e7f-486d-9ae3-b75888ec0867" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiser": "Brevanne",
    "analyze": true,
    "country": "US",
    "domain": "brevanne.myshopify.com",
    "maxAds": 3,
    "maxAnalyses": 3,
    "pageId": "229657833239852"
  }'
GET/competitors/{id}/funnel

Get a competitor's funnel

Each running ad (includeInactive for stopped ones too) read as top, middle or bottom of the funnel from its hook, offer, call to action, landing page and what Creative Memory found in it; per stage the ads, share, dominant hooks, angles, offers, calls to action, landing pages and formats; where the ads send people; the longest-running ads; and the angles they use that the workspace's own Creative Memory rarely shows, and the reverse (compare, default true). Also in MCP as analyze_competitor_funnel.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe competitor's ID.
comparequerystringOptionalCompare with the workspace's own Creative Memory (default true).
includeInactivequerystringOptionalStopped ads too (default: running ones only).
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

adsintegerRequired
Ads read.
advertiserobject or null
The competitor: id, name, pageId, domain, country, libraryUrl (its ads in the public Ad Library), researchedAt, ads, activeAds, analyzedAds.
analyzedinteger
Of those, with Creative Memory's findings.
byAdarray of objects
Each ad's stage, up to 60.
gapsobject or null
{ownAnalyzed, theyUse [{angle, theirs, yours}], onlyYou [...], note}: shares in percent.
landingFlowarray of objects
Kinds of landing page.
notestringRequired
How to read it.
pendinginteger
Still being read by Creative Memory.
stagesarray of objectsRequired
Top, middle and bottom.
topPagesarray of objects
The pages linked most.
winnersarray of objectsRequired
The longest-running ads.

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/competitors/c1bbc5f7-c690-45f1-acca-4911cfce6445/funnel" \
  -H "Authorization: Bearer $PLUTO_KEY"