Creative Memory
Search your media and ads by what's in them, and the indexing and credits behind it.
Search ads by copy and creative
A read carried in a POST body. Finds ads (current Pluto drafts and ads observed at Meta) by their copy, name and the recorded evidence of their media, or by similarity to an indexed example file (example, exclusive with q). Each result is the ad's current contextual revision: its copy, verified media, completeness, mediaEvidence and up to three matching copy fields or media moments. Any query word can match; a quoted phrase must appear with that exact wording and turns off meaning-based matching (semantic: literal). When the encoder is unavailable results fall back to text matching (semantic: unavailable). Results are ranked once into a snapshot of at most 200 ads; nextAfter pages through it for two minutes with the same body, and a 409 asks to search again when an ad, its media or the example changed. filters.tags keeps ads whose Pluto ad isn't archived and has any of those tags (an ad observed at Meta through the Pluto ad that published it; others have no tags). coverage counts eligible ads in scope (tags included, media type and length filters excluded), how many are searchable and how many are still being prepared; absence from results is not absence. Uses no credit, writes nothing and uses no allowance.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
after- The previous page's nextAfter; send the same q, filters and example.
exampleexample.evidenceId- Optional: one indexed observation of that file to match instead of the whole file.
example.mediaId- An indexed media file whose look to match.
filtersfilters.adAccountId- A Meta ad account, act_ followed by digits (act_123456789). Limits results to observed Meta ads.
filters.maxDurationMs- Only ads with a video at most this long.
filters.mediaKind- Only ads with media of this type.One of
image,video filters.minDurationMs- Only ads with a video at least this long.
filters.subjectKind- ad: current Pluto drafts. meta_ad: ads observed at Meta.One of
ad,meta_ad filters.tags- Tag (workflow label) IDs: only ads whose Pluto ad isn't archived and has any of them. An ad observed at Meta counts through the Pluto ad that published it; one Pluto didn't publish has no tags. Coverage then counts the tagged ads only.
limit- Ads per page, default 10 (up to 100); page on with
after. q- Words to find in ad copy, ad names and recorded media evidence; at most 500 characters. Any word can match. A "quoted phrase" must appear with that exact wording and turns off meaning-based matching. Empty lists the newest searchable ads. Leave empty when searching by example.
Response
coveragecoverage.indexed- Searchable ads in scope.
coverage.partial- Some eligible ads are not searchable yet; absence from results is not absence.
coverage.pending- Ads in scope still being prepared for search.
coverage.total- Eligible ads in scope (media type and length filters excluded).
items- This page of ads, best match first.
items[].contextitems[].context.assetsComplete- Whether the complete media composition is known.
items[].context.copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
items[].context.copyComplete- Whether all advertiser-supplied copy is represented.
items[].context.fingerprint- Version of this exact composition and source media.
items[].context.limitations- Why some composition or evidence remains unknown.
items[].context.mediaIds- Media available for evidence lookup.
items[].context.name- Creative name.
items[].context.observedAt- When this composition was observed.
items[].context.source- Draft, media or a recorded published Meta snapshot/readback.
items[].context.subjectitems[].context.subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad items[].context.subject.mediaId- Media in this workspace.
items[].context.subject.adId- Meta ad ID.
items[].context.subject.adAccountId- Optional Meta ad account ID.
items[].creativeRevisionId- The ad's current contextual revision (copy plus media identities).
items[].matches- Up to three matching copy fields or media observations.
items[].matches[].endMs- End within the original media.
items[].matches[].field- Copy field, e.g. copy.primaryText; null for media evidence.
items[].matches[].id- Copy field or evidence ID.
items[].matches[].mediaId- The media file this evidence is from.
items[].matches[].provenance- Where the text comes from, including correction status.
items[].matches[].source- copy for advertiser-supplied text; otherwise the media observation's source.
items[].matches[].startMs- Start within the original media.
items[].matches[].text- Recorded text, at most 4,000 characters.
items[].mediaEvidence- What Creative Memory has read of the ad's known media: complete, partial, or none (copy only).One of
complete,partial,none limitations- What this result set does not cover.
mode- How results were retrieved.One of
text,hybrid,example nextAfter- Cursor for the next page; results stay pinned for two minutes.
resultLimit- Most results one search keeps.
semantic- Meaning-based matching: used, not requested (browsing), off for quoted phrases, or unavailable (text matching only).One of
used,not_requested,literal,unavailable truncated- More candidates exist than the 200 kept; narrow the search. Not a count.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409The results changed or expired; search again.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/ad-search" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"after": "8eb642ac-0f98-4944-a008-281a86d19ea6",
"example": {
"evidenceId": "a20a2bd4-3cb6-4cf5-b44f-8ad205039b40",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
},
"filters": {
"adAccountId": "act_741877585619437",
"maxDurationMs": 12000,
"mediaKind": "image",
"minDurationMs": 12000,
"subjectKind": "ad",
"tags": [
"9f31d37e-2bee-42ac-bec0-da0ba0081d49"
]
},
"limit": 50,
"q": "vitamin c serum"
}'List files Creative Memory can add
Which files can be added to Creative Memory.
For up to 100 files, whether they can be added to Creative Memory now, by the same rule as a quote: allowed when the caller may change the workspace (never a guest or a read-only member), the organization isn't read-only and has Creative Memory (Enterprise). Each file: addable, analyzed (its current bytes were read in full), running (a request is reading it, requestId), waiting (the workspace's Add files to Creative Memory setting will read it: queued or waiting for credits) or unsupported (not a ready image or video). Starts nothing and uses no credits; the price comes from POST /creative-memory/quote.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
mediaIds | string | Optional | Media IDs, comma-separated, 1 to 100. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
allowed- Whether the caller may add files to Creative Memory now.
items- One per distinct file asked about.
items[].mediaId- The file.
items[].requestId- The request reading it, while
running. items[].requestedBy- Who asked for that request, while
running: a person, the Agent, the workspace's Add files to Creative Memory setting (system), or an API key (api_key).One ofperson,api_key,agent,system items[].state- Whether it can be added, and if not why.One of
addable,analyzed,running,waiting,unsupported
curl "$PLUTO_API/creative-memory/addable" \
-H "Authorization: Bearer $PLUTO_KEY"Compare recorded creative variants
Compare 2–8 distinct media, draft-ad or observed-Meta-ad subjects. Returns compositions, deduplicated media evidence capped at 64 observations each, explicit truncation and recorded copy/media differences. Unknown remains unknown. No new inference runs; similarity does not establish lineage or causality, and current composition must not be assigned to historical metrics.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
subjects- Two to eight distinct creatives, in comparison order.
subjects[].kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad subjects[].mediaId- Media in this workspace.
subjects[].adId- Meta ad ID.
subjects[].adAccountId- Optional Meta ad account ID.
Response
differences- Recorded copy and media differences; missing information cannot prove equality.
differences[].field- Copy or media field that differs.
differences[].values- One value per compared creative.
limitations- Coverage and interpretation limits; this read makes no causal or historical performance claim.
lineagelineage.families- Current family claims that include at least one compared revision.
lineage.families[].actorKind- Declarer category.One of
person,api_key,agent,system lineage.families[].basis- How the declarer documented the claim.One of
creator_declaration,workflow_record,similarity lineage.families[].limitations- The claim's recorded interpretation limits.
lineage.families[].members- All 2–32 recorded member revisions.
lineage.families[].members[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
lineage.families[].members[].fingerprint- Exact composition fingerprint the claim was recorded against.
lineage.families[].members[].subjectlineage.families[].members[].variantIndex- Position in
variantswhen this exact revision is compared; null when it is not. lineage.families[].name- Family name.
lineage.families[].recordId- Current immutable family record; read it for full sources.
lineage.families[].recordedAt- Server recording time.
lineage.families[].relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation lineage.families[].status- Recorded claim status. Similarity-based claims are never confirmed.One of
candidate,confirmed,rejected lineage.families[].supersedesId- Earlier record this claim amended.
lineage.limitations- Recorded claims are attributed declarations; similarity and shared media never establish lineage.
lineage.relations- Current variant claims that name at least one compared revision.
lineage.relations[].actorKind- Declarer category.One of
person,api_key,agent,system lineage.relations[].basis- How the declarer documented the claim.One of
creator_declaration,workflow_record,similarity lineage.relations[].changedComponents- Declared changed components; unlisted components are not proven unchanged.
lineage.relations[].childlineage.relations[].child.creativeRevisionId- Persisted ad composition revision; null for standalone media.
lineage.relations[].child.fingerprint- Exact composition fingerprint the claim was recorded against.
lineage.relations[].child.subjectlineage.relations[].child.variantIndex- Position in
variantswhen this exact revision is compared; null when it is not. lineage.relations[].familyId- Exact family record named by the claim.
lineage.relations[].limitations- The claim's recorded interpretation limits.
lineage.relations[].parentlineage.relations[].parent.creativeRevisionId- Persisted ad composition revision; null for standalone media.
lineage.relations[].parent.fingerprint- Exact composition fingerprint the claim was recorded against.
lineage.relations[].parent.subjectlineage.relations[].parent.variantIndex- Position in
variantswhen this exact revision is compared; null when it is not. lineage.relations[].recordId- Current immutable relationship record; read it for full sources.
lineage.relations[].recordedAt- Server recording time.
lineage.relations[].relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation lineage.relations[].status- Recorded claim status. Similarity-based claims are never confirmed.One of
candidate,confirmed,rejected lineage.relations[].supersedesId- Earlier record this claim amended.
lineage.truncated- More than 100 claims matched; this is not the complete family graph.
media- Deduplicated available media evidence.
media[].coveragemedia[].coverage.description- What was and was not examined.
media[].coverage.status- Readiness/coverage status.
media[].evidence- At most 64 source-linked observations for each media item.
media[].evidence[].endMs- Original-media end.
media[].evidence[].id- Source reference.
media[].evidence[].origin- Omitted for recorded model evidence. authorized_correction: a reviewed human correction, an attributed assertion rather than verified truth. revalidation_required: an observation that disagrees with an active correction; it cannot prove a condition.One of
authorized_correction,revalidation_required media[].evidence[].source- Evidence modality/source.
media[].evidence[].startMs- Original-media start.
media[].evidence[].text- Observed evidence.
media[].evidenceTruncated- Additional recorded evidence was omitted from this bounded comparison.
media[].mediaId- Shared source media appears once.
media[].summary- Published interpretation, if available.
variants- Creative compositions in requested order.
variants[].assetsComplete- Whether the complete media composition is known.
variants[].copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
variants[].copyComplete- Whether all advertiser-supplied copy is represented.
variants[].fingerprint- Version of this exact composition and source media.
variants[].limitations- Why some composition or evidence remains unknown.
variants[].mediaIds- Media available for evidence lookup.
variants[].name- Creative name.
variants[].observedAt- When this composition was observed.
variants[].source- Draft, media or a recorded published Meta snapshot/readback.
variants[].subjectvariants[].subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad variants[].subject.mediaId- Media in this workspace.
variants[].subject.adId- Meta ad ID.
variants[].subject.adAccountId- Optional Meta ad account ID.
curl -X POST "$PLUTO_API/creative-memory/compare" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"subjects": [
{
"kind": "media",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
},
{
"kind": "media",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}
]
}'Resolve creative composition
Read a media item, current Pluto draft or observed published Meta ad. Returns copy, verified available media, composition fingerprint, observation time and explicit completeness. Uses no credit and starts no provider request; published context never substitutes the current edited draft.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad mediaId- Media in this workspace.
adId- Meta ad ID.
adAccountId- Optional Meta ad account ID.
Response
assetsComplete- Whether the complete media composition is known.
copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
copyComplete- Whether all advertiser-supplied copy is represented.
fingerprint- Version of this exact composition and source media.
limitations- Why some composition or evidence remains unknown.
mediaIds- Media available for evidence lookup.
name- Creative name.
observedAt- When this composition was observed.
source- Draft, media or a recorded published Meta snapshot/readback.
subjectsubject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad subject.mediaId- Media in this workspace.
subject.adId- Meta ad ID.
subject.adAccountId- Optional Meta ad account ID.
curl -X POST "$PLUTO_API/creative-memory/context" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "media",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}'List evidence corrections
Immutable correction and release revisions, newest first, including those for earlier source versions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
mediaId | string | Optional | Optional media filter. |
after | string | Optional | Previous nextAfter ID. |
limit | string | Optional | 1–100, default 30. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].actorId- Recorded actor.
items[].actorKind- Actual actor origin.One of
person,api_key,agent,system items[].assetId- Exact verified asset.
items[].beforeitems[].before.endMs- Original-media end.
items[].before.id- Raw evidence or immutable correction ID.
items[].before.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
items[].before.publicationId- Effective publication source.
items[].before.source- Original evidence modality.
items[].before.sourceRef- Original or conflict-qualified source reference.
items[].before.startMs- Original-media start.
items[].before.text- Recorded text.
items[].createdAt- Server publication time.
items[].id- Immutable correction revision.
items[].limitations- Evidence is attributed, lexical-ready, and not independently verified.
items[].mediaId- Media.
items[].operation- Explicit correction or release.One of
edit,release items[].patchIds- Effective patch set after this command.
items[].previousId- Previous overlay head.
items[].provenanceitems[].provenance.auditIdsitems[].provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity items[].provenance.note- Document how this relationship or allocation is known.
items[].provenance.referencesitems[].provenance.references[].observedAt- When the declarer observed this source, no future dates.
items[].provenance.references[].title- Source document title.
items[].provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
items[].publicationIds- Accepted publication set.
items[].rationale- Recorded rationale.
items[].rebasesCorrectionId- Historical edit explicitly rebased.
items[].replacementitems[].replacement.endMs- Original video end, null for images.
items[].replacement.startMs- Original video start, null for images.
items[].replacement.textitems[].schemaVersion- Correction contract version.
items[].sourceFingerprint- Source version.
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/corrections" \
-H "Authorization: Bearer $PLUTO_KEY"Correct or retract evidence
Replaces (or, with replacement: null, retracts) one effective evidence entry of the reviewed snapshot. The correction is an attributed assertion, not verified truth: the new wording is searchable at once without a semantic vector, the original vector and model interpretations stop competing, and later compatible processing keeps the edit while changed overlapping observations are flagged for revalidation. Dispatches no model call.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
evidenceId- Exact effective evidence reviewed.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationale- Why the source supports this correction.
rebasesCorrectionId- Optional historical correction being explicitly rebased onto the newly reviewed evidence.
replacement- An explicit replacement; null explicitly retracts this evidence.
replacement.endMs- Original video end, null for images.
replacement.startMs- Original video start, null for images.
replacement.textsnapshotsnapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdssnapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
snapshot.mediaId- Exact source media.
Response
actorId- Recorded actor.
actorKind- Actual actor origin.One of
person,api_key,agent,system assetId- Exact verified asset.
beforebefore.endMs- Original-media end.
before.id- Raw evidence or immutable correction ID.
before.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationId- Effective publication source.
before.source- Original evidence modality.
before.sourceRef- Original or conflict-qualified source reference.
before.startMs- Original-media start.
before.text- Recorded text.
createdAt- Server publication time.
id- Immutable correction revision.
limitations- Evidence is attributed, lexical-ready, and not independently verified.
mediaId- Media.
operation- Explicit correction or release.One of
edit,release patchIds- Effective patch set after this command.
previousId- Previous overlay head.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIds- Accepted publication set.
rationale- Recorded rationale.
rebasesCorrectionId- Historical edit explicitly rebased.
replacementreplacement.endMs- Original video end, null for images.
replacement.startMs- Original video start, null for images.
replacement.textschemaVersion- Correction contract version.
sourceFingerprint- Source version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409The source, published evidence or corrections changed since review; read the context again and rebase explicitly.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/corrections" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 64a35872-f947-4c8e-b12e-54f3ca0384af" \
-H "Content-Type: application/json" \
-d '{
"evidenceId": "a20a2bd4-3cb6-4cf5-b44f-8ad205039b40",
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"rationale": "Spend is pacing ahead of plan; hold the budget until Friday.",
"rebasesCorrectionId": "9578d4d1-10a9-4fa6-bfe8-1f59f245c421",
"replacement": {
"endMs": 12000,
"startMs": 12000,
"text": "Can we try the 4x5 cut for Instagram feed before we publish?"
},
"snapshot": {
"expectedCorrectionId": "be793c5e-2d9d-4e66-acae-709a7c022109",
"expectedPublicationIds": [
"a4611f0e-475f-48e8-851b-59c1f6844ffb"
],
"expectedSourceFingerprint": "1c70088ea7663d97",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}
}'Release all corrections for a source
Deactivates every active correction for the reviewed source and restores its current raw evidence, keeping all history. Precision results computed under the earlier corrections stay stale; request a new one if needed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationale- Why all active corrections for this exact source are being released.
snapshotsnapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdssnapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
snapshot.mediaId- Exact source media.
Response
actorId- Recorded actor.
actorKind- Actual actor origin.One of
person,api_key,agent,system assetId- Exact verified asset.
beforebefore.endMs- Original-media end.
before.id- Raw evidence or immutable correction ID.
before.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationId- Effective publication source.
before.source- Original evidence modality.
before.sourceRef- Original or conflict-qualified source reference.
before.startMs- Original-media start.
before.text- Recorded text.
createdAt- Server publication time.
id- Immutable correction revision.
limitations- Evidence is attributed, lexical-ready, and not independently verified.
mediaId- Media.
operation- Explicit correction or release.One of
edit,release patchIds- Effective patch set after this command.
previousId- Previous overlay head.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIds- Accepted publication set.
rationale- Recorded rationale.
rebasesCorrectionId- Historical edit explicitly rebased.
replacementreplacement.endMs- Original video end, null for images.
replacement.startMs- Original video start, null for images.
replacement.textschemaVersion- Correction contract version.
sourceFingerprint- Source version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409The snapshot changed or there is nothing to release.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/corrections/release" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2ddd01c2-3297-4c5f-a17f-78217a16a100" \
-H "Content-Type: application/json" \
-d '{
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"rationale": "Spend is pacing ahead of plan; hold the budget until Friday.",
"snapshot": {
"expectedCorrectionId": "be793c5e-2d9d-4e66-acae-709a7c022109",
"expectedPublicationIds": [
"a4611f0e-475f-48e8-851b-59c1f6844ffb"
],
"expectedSourceFingerprint": "1c70088ea7663d97",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}
}'Read an evidence correction
One immutable correction or release revision with the reviewed before value, replacement, rationale and actor provenance.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The correction's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
actorId- Recorded actor.
actorKind- Actual actor origin.One of
person,api_key,agent,system assetId- Exact verified asset.
beforebefore.endMs- Original-media end.
before.id- Raw evidence or immutable correction ID.
before.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationId- Effective publication source.
before.source- Original evidence modality.
before.sourceRef- Original or conflict-qualified source reference.
before.startMs- Original-media start.
before.text- Recorded text.
createdAt- Server publication time.
id- Immutable correction revision.
limitations- Evidence is attributed, lexical-ready, and not independently verified.
mediaId- Media.
operation- Explicit correction or release.One of
edit,release patchIds- Effective patch set after this command.
previousId- Previous overlay head.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIds- Accepted publication set.
rationale- Recorded rationale.
rebasesCorrectionId- Historical edit explicitly rebased.
replacementreplacement.endMs- Original video end, null for images.
replacement.startMs- Original video start, null for images.
replacement.textschemaVersion- Correction contract version.
sourceFingerprint- Source version.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/corrections/82917378-5081-49d8-9889-357a567c9099" \
-H "Authorization: Bearer $PLUTO_KEY"Evaluate a recorded creative condition
Exact three-valued evaluation over current recorded evidence, with original-media time scopes and cited results. Unknown remains unknown through negation. Literal false describes the recorded transcript/text, not physical absence. No ranked search or paid inference runs. Conditions are bounded to 64 nodes, 6 levels and 500-character phrases.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
conditioncondition.caseSensitive- Defaults to false.
condition.op- Bounded recorded-evidence temporal predicate.One of
repetitions condition.text- Literal phrase in recorded evidence; 1-500 characters. This does not assert physical absence.
condition.kind- Interpretation feature. Missing interpretations remain unknown.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.condition- A condition with op speech, on_screen_text, feature, before, within, starts_before, after, relative_window, overlaps, duration, first_occurrence, repetitions, all, any or not, using the same fields as the parent alternatives. At most 64 nodes and 6 levels in total.
condition.endMs- Exclusive end greater than start. Prior coverage is required.
condition.startMs- Inclusive original-source start of first-occurrence window within evaluated scope.
condition.conditions- One or more child conditions.
condition.eventcondition.event.caseSensitive- Defaults to false.
condition.event.op- Recorded interpretation, not a detector of absence.One of
feature condition.event.textcondition.event.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.toleranceMs- Default 0. Expands accepted comparison thresholds only; not calibrated model accuracy.
condition.anchorcondition.anchor.caseSensitive- Defaults to false.
condition.anchor.op- Recorded interpretation, not a detector of absence.One of
feature condition.anchor.textcondition.anchor.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.maxDelayMs- Inclusive maximum delay, at least minDelayMs.
condition.minDelayMs- Inclusive minimum start-of-event minus end-of-anchor delay; default 0.
condition.anchorEdge- Anchor endpoint; event uses its start.One of
start,end condition.endOffsetMs- Signed original-time offset from the selected anchor edge.
condition.startOffsetMs- Signed original-time offset from the selected anchor edge.
condition.leftcondition.left.caseSensitive- Defaults to false.
condition.left.op- Recorded interpretation, not a detector of absence.One of
feature condition.left.textcondition.left.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.minOverlapMs- Positive supported overlap; touching endpoints and broad intersecting envelopes are insufficient.
condition.rightcondition.right.caseSensitive- Defaults to false.
condition.right.op- Recorded interpretation, not a detector of absence.One of
feature condition.right.textcondition.right.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.maxMs- Inclusive maximum occurrence duration, at least minMs. A transcript container is not a phrase duration.
condition.minMs- Inclusive minimum occurrence duration.
condition.maxCount- Optional inclusive maximum. Missing coverage cannot establish an upper count. Sampled visual persistence is not repetitions.
condition.minCountmediaId- Media in this workspace.
scopescope.endMs- Exclusive original-media end.
scope.startMs- Inclusive original-media start.
Response
conditioncondition.caseSensitive- Defaults to false.
condition.op- Bounded recorded-evidence temporal predicate.One of
repetitions condition.text- Literal phrase in recorded evidence; 1-500 characters. This does not assert physical absence.
condition.kind- Interpretation feature. Missing interpretations remain unknown.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.condition- A condition with op speech, on_screen_text, feature, before, within, starts_before, after, relative_window, overlaps, duration, first_occurrence, repetitions, all, any or not, using the same fields as the parent alternatives. At most 64 nodes and 6 levels in total.
condition.endMs- Exclusive end greater than start. Prior coverage is required.
condition.startMs- Inclusive original-source start of first-occurrence window within evaluated scope.
condition.conditions- One or more child conditions.
condition.eventcondition.event.caseSensitive- Defaults to false.
condition.event.op- Recorded interpretation, not a detector of absence.One of
feature condition.event.textcondition.event.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.toleranceMs- Default 0. Expands accepted comparison thresholds only; not calibrated model accuracy.
condition.anchorcondition.anchor.caseSensitive- Defaults to false.
condition.anchor.op- Recorded interpretation, not a detector of absence.One of
feature condition.anchor.textcondition.anchor.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.maxDelayMs- Inclusive maximum delay, at least minDelayMs.
condition.minDelayMs- Inclusive minimum start-of-event minus end-of-anchor delay; default 0.
condition.anchorEdge- Anchor endpoint; event uses its start.One of
start,end condition.endOffsetMs- Signed original-time offset from the selected anchor edge.
condition.startOffsetMs- Signed original-time offset from the selected anchor edge.
condition.leftcondition.left.caseSensitive- Defaults to false.
condition.left.op- Recorded interpretation, not a detector of absence.One of
feature condition.left.textcondition.left.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.minOverlapMs- Positive supported overlap; touching endpoints and broad intersecting envelopes are insufficient.
condition.rightcondition.right.caseSensitive- Defaults to false.
condition.right.op- Recorded interpretation, not a detector of absence.One of
feature condition.right.textcondition.right.kind- Feature type.One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio condition.maxMs- Inclusive maximum occurrence duration, at least minMs. A transcript container is not a phrase duration.
condition.minMs- Inclusive minimum occurrence duration.
condition.maxCount- Optional inclusive maximum. Missing coverage cannot establish an upper count. Sampled visual persistence is not repetitions.
condition.minCountcorrectionHeadId- Current authorized correction generation included in the evaluation fingerprint.
coverage- Missing, partial or truncated evidence remains explicit.
evaluationHash- Condition, source and active evidence generation fingerprint.
evidence- Cited supporting observations.
evidence[].endMs- Original-media end.
evidence[].id- Source reference.
evidence[].origin- Omitted for recorded model evidence. authorized_correction: a reviewed human correction, an attributed assertion rather than verified truth. revalidation_required: an observation that disagrees with an active correction; it cannot prove a condition.One of
authorized_correction,revalidation_required evidence[].source- Evidence modality/source.
evidence[].startMs- Original-media start.
evidence[].text- Observed evidence.
predicateHash- Canonical condition and scope fingerprint.
scopescope.endMs- Exclusive original-source end.
scope.startMs- Inclusive original-source start.
semantics- Results describe recorded evidence, not certified physical truth.One of
recorded_evidence sourceRevision- Exact current source fingerprint.
value- Three-valued result over recorded evidence, not physical ground truth.One of
true,false,unknown version- Predicate semantics version.
curl -X POST "$PLUTO_API/creative-memory/evaluate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"condition": {
"caseSensitive": true,
"op": "speech",
"text": "Can we try the 4x5 cut for Instagram feed before we publish?"
},
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"scope": {
"endMs": 12000,
"startMs": 12000
}
}'List registered creative experiments
Newest first, each with its current immutable design revision. Registration is a declaration: allocation, randomization and causal effects are never inferred.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Previous nextAfter experiment ID. |
limit | string | Optional | 1–100, default 40. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].createdAt- First registration.
items[].currentVersion- Latest immutable design version.
items[].firstAssessedAt- Earliest Pluto outcome-read attempt; retained even if reading failed.
items[].id- Experiment ID.
items[].revisionitems[].revision.actorId- Declaring actor.
items[].revision.actorKind- Actor category.One of
person,api_key,agent,system items[].revision.amendmentReason- Why an immutable revision was appended.
items[].revision.designitems[].revision.design.allocationitems[].revision.design.counterarguments- Alternative explanations that may falsify the hypothesis.
items[].revision.design.creativeChange- The planned intervention and what differs.
items[].revision.design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
items[].revision.design.groupsitems[].revision.design.heldConstant- Conditions intended to remain equal.
items[].revision.design.hypothesis- Falsifiable hypothesis recorded before results.
items[].revision.design.knownConfounders- Known differences that limit attribution.
items[].revision.design.name- Experiment name.
items[].revision.design.primaryMetricitems[].revision.design.stoppingRuleitems[].revision.design.windowitems[].revision.experimentId- Experiment ID.
items[].revision.fingerprint- Versioned immutable design and source fingerprint.
items[].revision.limitations- Design and causal-inference limitations.
items[].revision.preregistered- This revision was registered before its window and any declared or recorded assessment; no causal proof.
items[].revision.priorResultsSeen- Registrant's current attestation.
items[].revision.registeredAt- Server registration time.
items[].revision.registrationTiming- Server-calculated temporal qualification.One of
prospective,historical_window,prior_results_declared,amendment_after_assessment,amendment_after_start items[].revision.schemaVersion- Design contract version.
items[].revision.sources- Source-backed comparison groups.
items[].revision.sources[].creatives- Exact server-resolved revisions.
items[].revision.sources[].groupKey- Registered comparison group.
items[].revision.version- Immutable design version.
items[].status- Current administrative status; not an inference result.One of
registered,running,completed,cancelled items[].updatedAt- Latest administrative change.
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/experiments" \
-H "Authorization: Bearer $PLUTO_KEY"Register a creative experiment
Records an immutable design pinned to exact reviewed creative revisions (expectedFingerprint from the context read). The server decides whether the revision is preregistered: only a window that has not begun, with no declared or recorded prior assessment, qualifies. Nothing is launched, allocated or spent.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
designdesign.allocationdesign.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational design.allocation.procedure- Document assignment mechanism and planned allocation.
design.allocation.provenancedesign.allocation.provenance.auditIdsdesign.allocation.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity design.allocation.provenance.note- Document how this relationship or allocation is known.
design.allocation.provenance.referencesdesign.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block design.allocation.unitDefinition- Define the eligible experimental unit and population.
design.counterarguments- Alternative explanations that may falsify the hypothesis.
design.creativeChange- The planned intervention and what differs.
design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
design.groupsdesign.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
design.groups[].creativesdesign.groups[].creatives[].expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
design.groups[].creatives[].subjectdesign.groups[].keydesign.groups[].name- Comparison group name.
design.groups[].role- Exactly one control.One of
control,treatment design.heldConstant- Conditions intended to remain equal.
design.hypothesis- Falsifiable hypothesis recorded before results.
design.knownConfounders- Known differences that limit attribution.
design.name- Experiment name.
design.primaryMetricdesign.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 design.stoppingRuledesign.stoppingRule.kind- One of
sequential design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
design.stoppingRule.maximumLooksdesign.stoppingRule.schedule- Prespecified analysis schedule.
design.windowdesign.window.currency- Accepted ISO currency matching all enrolled accounts.
design.window.since- Inclusive first account-local day.
design.window.timezone- IANA timezone matching all enrolled accounts.
design.window.until- Inclusive last day; at most 31 days.
priorResultsSeen- Whether anyone registering this revision has already assessed relevant results outside this recording. Must be truthful.
Response
createdAt- First registration.
currentVersion- Latest immutable design version.
firstAssessedAt- Earliest Pluto outcome-read attempt; retained even if reading failed.
id- Experiment ID.
revisionrevision.actorId- Declaring actor.
revision.actorKind- Actor category.One of
person,api_key,agent,system revision.amendmentReason- Why an immutable revision was appended.
revision.designrevision.design.allocationrevision.design.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
revision.design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational revision.design.allocation.procedure- Document assignment mechanism and planned allocation.
revision.design.allocation.provenancerevision.design.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block revision.design.allocation.unitDefinition- Define the eligible experimental unit and population.
revision.design.counterarguments- Alternative explanations that may falsify the hypothesis.
revision.design.creativeChange- The planned intervention and what differs.
revision.design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
revision.design.groupsrevision.design.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesrevision.design.groups[].keyrevision.design.groups[].name- Comparison group name.
revision.design.groups[].role- Exactly one control.One of
control,treatment revision.design.heldConstant- Conditions intended to remain equal.
revision.design.hypothesis- Falsifiable hypothesis recorded before results.
revision.design.knownConfounders- Known differences that limit attribution.
revision.design.name- Experiment name.
revision.design.primaryMetricrevision.design.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click revision.design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease revision.design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.stoppingRulerevision.design.stoppingRule.kind- One of
sequential revision.design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksrevision.design.stoppingRule.schedule- Prespecified analysis schedule.
revision.design.windowrevision.design.window.currency- Accepted ISO currency matching all enrolled accounts.
revision.design.window.since- Inclusive first account-local day.
revision.design.window.timezone- IANA timezone matching all enrolled accounts.
revision.design.window.until- Inclusive last day; at most 31 days.
revision.experimentId- Experiment ID.
revision.fingerprint- Versioned immutable design and source fingerprint.
revision.limitations- Design and causal-inference limitations.
revision.preregistered- This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeen- Registrant's current attestation.
revision.registeredAt- Server registration time.
revision.registrationTiming- Server-calculated temporal qualification.One of
prospective,historical_window,prior_results_declared,amendment_after_assessment,amendment_after_start revision.schemaVersion- Design contract version.
revision.sources- Source-backed comparison groups.
revision.sources[].creatives- Exact server-resolved revisions.
revision.sources[].creatives[].assets- Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextrevision.sources[].creatives[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryrevision.sources[].groupKey- Registered comparison group.
revision.version- Immutable design version.
status- Current administrative status; not an inference result.One of
registered,running,completed,cancelled updatedAt- Latest administrative change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409A creative changed since it was reviewed; read its current revision.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/experiments" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2e1b7efb-5b92-4fd6-ade0-eb35262b39b2" \
-H "Content-Type: application/json" \
-d '{
"design": {
"allocation": {
"interferencePolicy": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"method": "randomized",
"procedure": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"unit": "person",
"unitDefinition": "UGC 9x16 against the studio cut, same budget and audience, for two weeks."
},
"counterarguments": [
"1000"
],
"creativeChange": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"creativeChangeIsolated": true,
"groups": [
{
"allocationShare": "0.18",
"creatives": [
{
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {}
}
],
"key": "sk_rNyDixNeo4NsQFbMiRxc8a3HhjrmBESS",
"name": "Vitamin C Serum, UGC 9x16",
"role": "control"
},
{
"allocationShare": "0.18",
"creatives": [
{
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {}
}
],
"key": "sk_rNyDixNeo4NsQFbMiRxc8a3HhjrmBESS",
"name": "Vitamin C Serum, UGC 9x16",
"role": "control"
}
],
"heldConstant": [
"Brevanne"
],
"hypothesis": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"knownConfounders": [
"Brevanne"
],
"name": "Vitamin C Serum, UGC 9x16",
"primaryMetric": {
"attribution": "7d_click_1d_view",
"definition": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"denominator": "spend",
"direction": "increase",
"numerator": "spend"
},
"stoppingRule": {
"kind": "fixed_window",
"minimumUnitsPerGroup": "1000"
},
"window": {
"currency": "USD",
"since": "2026-09-01",
"timezone": "America/New_York",
"until": "2026-09-27"
}
},
"priorResultsSeen": true
}'Read a creative experiment
Reads the experiment with the requested immutable design revision, its source snapshots, registration timing and limitations.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The experiment's ID. |
version | string | Optional | Immutable design version; default is the current one. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- First registration.
currentVersion- Latest immutable design version.
firstAssessedAt- Earliest Pluto outcome-read attempt; retained even if reading failed.
id- Experiment ID.
revisionrevision.actorId- Declaring actor.
revision.actorKind- Actor category.One of
person,api_key,agent,system revision.amendmentReason- Why an immutable revision was appended.
revision.designrevision.design.allocationrevision.design.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
revision.design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational revision.design.allocation.procedure- Document assignment mechanism and planned allocation.
revision.design.allocation.provenancerevision.design.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block revision.design.allocation.unitDefinition- Define the eligible experimental unit and population.
revision.design.counterarguments- Alternative explanations that may falsify the hypothesis.
revision.design.creativeChange- The planned intervention and what differs.
revision.design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
revision.design.groupsrevision.design.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesrevision.design.groups[].keyrevision.design.groups[].name- Comparison group name.
revision.design.groups[].role- Exactly one control.One of
control,treatment revision.design.heldConstant- Conditions intended to remain equal.
revision.design.hypothesis- Falsifiable hypothesis recorded before results.
revision.design.knownConfounders- Known differences that limit attribution.
revision.design.name- Experiment name.
revision.design.primaryMetricrevision.design.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click revision.design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease revision.design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.stoppingRulerevision.design.stoppingRule.kind- One of
sequential revision.design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksrevision.design.stoppingRule.schedule- Prespecified analysis schedule.
revision.design.windowrevision.design.window.currency- Accepted ISO currency matching all enrolled accounts.
revision.design.window.since- Inclusive first account-local day.
revision.design.window.timezone- IANA timezone matching all enrolled accounts.
revision.design.window.until- Inclusive last day; at most 31 days.
revision.experimentId- Experiment ID.
revision.fingerprint- Versioned immutable design and source fingerprint.
revision.limitations- Design and causal-inference limitations.
revision.preregistered- This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeen- Registrant's current attestation.
revision.registeredAt- Server registration time.
revision.registrationTiming- Server-calculated temporal qualification.One of
prospective,historical_window,prior_results_declared,amendment_after_assessment,amendment_after_start revision.schemaVersion- Design contract version.
revision.sources- Source-backed comparison groups.
revision.sources[].creatives- Exact server-resolved revisions.
revision.sources[].creatives[].assets- Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextrevision.sources[].creatives[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryrevision.sources[].groupKey- Registered comparison group.
revision.version- Immutable design version.
status- Current administrative status; not an inference result.One of
registered,running,completed,cancelled updatedAt- Latest administrative change.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26" \
-H "Authorization: Bearer $PLUTO_KEY"Amend a creative experiment design
Appends a new immutable design revision for the reviewed expectedVersion. Earlier revisions keep their original qualification; an amendment after the window started, after declared prior results or after any recorded assessment can never become preregistered.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The experiment's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
designdesign.allocationdesign.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational design.allocation.procedure- Document assignment mechanism and planned allocation.
design.allocation.provenancedesign.allocation.provenance.auditIdsdesign.allocation.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity design.allocation.provenance.note- Document how this relationship or allocation is known.
design.allocation.provenance.referencesdesign.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block design.allocation.unitDefinition- Define the eligible experimental unit and population.
design.counterarguments- Alternative explanations that may falsify the hypothesis.
design.creativeChange- The planned intervention and what differs.
design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
design.groupsdesign.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
design.groups[].creativesdesign.groups[].creatives[].expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
design.groups[].creatives[].subjectdesign.groups[].keydesign.groups[].name- Comparison group name.
design.groups[].role- Exactly one control.One of
control,treatment design.heldConstant- Conditions intended to remain equal.
design.hypothesis- Falsifiable hypothesis recorded before results.
design.knownConfounders- Known differences that limit attribution.
design.name- Experiment name.
design.primaryMetricdesign.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 design.stoppingRuledesign.stoppingRule.kind- One of
sequential design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
design.stoppingRule.maximumLooksdesign.stoppingRule.schedule- Prespecified analysis schedule.
design.windowdesign.window.currency- Accepted ISO currency matching all enrolled accounts.
design.window.since- Inclusive first account-local day.
design.window.timezone- IANA timezone matching all enrolled accounts.
design.window.until- Inclusive last day; at most 31 days.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
priorResultsSeen- Whether relevant results have already been assessed.
reason- Why the registered design is amended.
Response
createdAt- First registration.
currentVersion- Latest immutable design version.
firstAssessedAt- Earliest Pluto outcome-read attempt; retained even if reading failed.
id- Experiment ID.
revisionrevision.actorId- Declaring actor.
revision.actorKind- Actor category.One of
person,api_key,agent,system revision.amendmentReason- Why an immutable revision was appended.
revision.designrevision.design.allocationrevision.design.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
revision.design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational revision.design.allocation.procedure- Document assignment mechanism and planned allocation.
revision.design.allocation.provenancerevision.design.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block revision.design.allocation.unitDefinition- Define the eligible experimental unit and population.
revision.design.counterarguments- Alternative explanations that may falsify the hypothesis.
revision.design.creativeChange- The planned intervention and what differs.
revision.design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
revision.design.groupsrevision.design.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesrevision.design.groups[].keyrevision.design.groups[].name- Comparison group name.
revision.design.groups[].role- Exactly one control.One of
control,treatment revision.design.heldConstant- Conditions intended to remain equal.
revision.design.hypothesis- Falsifiable hypothesis recorded before results.
revision.design.knownConfounders- Known differences that limit attribution.
revision.design.name- Experiment name.
revision.design.primaryMetricrevision.design.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click revision.design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease revision.design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.stoppingRulerevision.design.stoppingRule.kind- One of
sequential revision.design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksrevision.design.stoppingRule.schedule- Prespecified analysis schedule.
revision.design.windowrevision.design.window.currency- Accepted ISO currency matching all enrolled accounts.
revision.design.window.since- Inclusive first account-local day.
revision.design.window.timezone- IANA timezone matching all enrolled accounts.
revision.design.window.until- Inclusive last day; at most 31 days.
revision.experimentId- Experiment ID.
revision.fingerprint- Versioned immutable design and source fingerprint.
revision.limitations- Design and causal-inference limitations.
revision.preregistered- This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeen- Registrant's current attestation.
revision.registeredAt- Server registration time.
revision.registrationTiming- Server-calculated temporal qualification.One of
prospective,historical_window,prior_results_declared,amendment_after_assessment,amendment_after_start revision.schemaVersion- Design contract version.
revision.sources- Source-backed comparison groups.
revision.sources[].creatives- Exact server-resolved revisions.
revision.sources[].creatives[].assets- Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextrevision.sources[].creatives[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryrevision.sources[].groupKey- Registered comparison group.
revision.version- Immutable design version.
status- Current administrative status; not an inference result.One of
registered,running,completed,cancelled updatedAt- Latest administrative change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The experiment or a creative changed; review the latest version.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26/amendments" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 897fa3d3-6e9c-4c6a-b27a-4b9defea649f" \
-H "Content-Type: application/json" \
-d '{
"design": {
"allocation": {
"interferencePolicy": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"method": "randomized",
"procedure": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"unit": "person",
"unitDefinition": "UGC 9x16 against the studio cut, same budget and audience, for two weeks."
},
"counterarguments": [
"1000"
],
"creativeChange": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"creativeChangeIsolated": true,
"groups": [
{
"allocationShare": "0.18",
"creatives": [
{
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {}
}
],
"key": "sk_rNyDixNeo4NsQFbMiRxc8a3HhjrmBESS",
"name": "Vitamin C Serum, UGC 9x16",
"role": "control"
},
{
"allocationShare": "0.18",
"creatives": [
{
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {}
}
],
"key": "sk_rNyDixNeo4NsQFbMiRxc8a3HhjrmBESS",
"name": "Vitamin C Serum, UGC 9x16",
"role": "control"
}
],
"heldConstant": [
"Brevanne"
],
"hypothesis": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"knownConfounders": [
"Brevanne"
],
"name": "Vitamin C Serum, UGC 9x16",
"primaryMetric": {
"attribution": "7d_click_1d_view",
"definition": "UGC 9x16 against the studio cut, same budget and audience, for two weeks.",
"denominator": "spend",
"direction": "increase",
"numerator": "spend"
},
"stoppingRule": {
"kind": "fixed_window",
"minimumUnitsPerGroup": "1000"
},
"window": {
"currency": "USD",
"since": "2026-09-01",
"timezone": "America/New_York",
"until": "2026-09-27"
}
},
"expectedVersion": 3,
"priorResultsSeen": true,
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'List observed experiment outcomes
Immutable outcome snapshots, each pinned to the design version it assessed. Every outcome is descriptive only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The experiment's ID. |
after | string | Optional | Previous nextAfter outcome ID. |
limit | string | Optional | 1–50, default 20. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].actorId- Assessing actor.
items[].actorKind- Actor category.One of
person,api_key,agent,system items[].designFingerprint- Exact assessed source and design identity.
items[].designVersion- Exact assessed design version.
items[].experimentId- Experiment.
items[].factsitems[].facts.attribution- Requested provider attribution window.
items[].facts.limitations- Coverage, observation, delivery and causal limitations.
items[].facts.maxBracketHours- Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
items[].facts.missingAdIds- Missing days and metrics are not zero-filled.
items[].facts.requestedAdIds- Requested ads.
items[].facts.retrievedAt- When Pluto assembled this read.
items[].facts.rows- Original ad/day facts; outcomes are never duplicated or allocated to each asset.
items[].facts.rows[].actionValues- The value of each action type, in the account currency.
items[].facts.rows[].actions- Every action type Meta counted that day in the attribution window, by Meta's action type (omni_purchase, lead, post_reaction, offsite_conversion.custom.<id>, …); absent: not reported.
items[].facts.rows[].adAccountId- Source Meta ad account.
items[].facts.rows[].adId- Source Meta ad.
items[].facts.rows[].adsetId- Reported ad set.
items[].facts.rows[].attribution- Exact provider attribution window.
items[].facts.rows[].campaignId- Reported campaign.
items[].facts.rows[].compositionitems[].facts.rows[].currency- Reported account currency.
items[].facts.rows[].dateitems[].facts.rows[].denominators- Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
items[].facts.rows[].fetchedAt- When this latest stored provider fact was fetched; not a point-in-time training snapshot.
items[].facts.rows[].metrics- Provider ad/day metrics as decimal strings (with video plays, 100% plays, average watch time in seconds and unique clicks); null stays unknown. Daily reach and unique clicks are not additive.
items[].facts.rows[].rankings- Meta's rankings of the ad that day: quality, engagementRate, conversionRate (ABOVE_AVERAGE, AVERAGE, BELOW_AVERAGE_35, BELOW_AVERAGE_20, BELOW_AVERAGE_10, UNKNOWN); absent when Meta gave none.
items[].facts.rows[].resultIndicator- Provider result indicator, when reported.
items[].facts.rows[].timezone- Reported account timezone used for the day.
items[].facts.sinceitems[].facts.untilitems[].factsFingerprint- Hash of the exact preserved facts.
items[].groupAdIdsitems[].id- Immutable observed outcome ID.
items[].inference- One of
descriptive_only items[].limitations- Sample, allocation, stopping and composition caveats.
items[].note- Recorded capture reason.
items[].observedAt- Snapshot capture time.
items[].until- Captured end day.
nextAfter- 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.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26/outcomes" \
-H "Authorization: Bearer $PLUTO_KEY"Record an observed experiment outcome
Snapshots stored provider ad/day facts for each group's registered delivery ads over completed account-local days inside the window. No metrics are accepted from the caller. Missing days and null metrics stay unknown, results are never allocated to assets, and the first assessment is recorded before reading so it cannot be hidden by a later amendment.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The experiment's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
note- Reason for taking this immutable outcome snapshot.
until- Completed account-local end day inside the registered window.
Response
actorId- Assessing actor.
actorKind- Actor category.One of
person,api_key,agent,system designFingerprint- Exact assessed source and design identity.
designVersion- Exact assessed design version.
experimentId- Experiment.
factsfacts.attribution- Requested provider attribution window.
facts.limitations- Coverage, observation, delivery and causal limitations.
facts.maxBracketHours- Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
facts.missingAdIds- Missing days and metrics are not zero-filled.
facts.requestedAdIds- Requested ads.
facts.retrievedAt- When Pluto assembled this read.
facts.rows- Original ad/day facts; outcomes are never duplicated or allocated to each asset.
facts.rows[].actionValues- The value of each action type, in the account currency.
facts.rows[].actions- Every action type Meta counted that day in the attribution window, by Meta's action type (omni_purchase, lead, post_reaction, offsite_conversion.custom.<id>, …); absent: not reported.
facts.rows[].adAccountId- Source Meta ad account.
facts.rows[].adId- Source Meta ad.
facts.rows[].adsetId- Reported ad set.
facts.rows[].attribution- Exact provider attribution window.
facts.rows[].campaignId- Reported campaign.
facts.rows[].compositionfacts.rows[].composition.assumedContinuity- True means matching snapshots assume continuity; intermediate changes were not observed.
facts.rows[].composition.creativeId- Only set for an observed stable bracket; not a delivered dynamic asset ID.
facts.rows[].composition.firstObservedAt- Earliest supporting observation time.
facts.rows[].composition.lastObservedAt- Latest supporting observation time.
facts.rows[].composition.observationCount- Supporting observations.
facts.rows[].composition.reason- Why composition is stable, mixed or unknown.
facts.rows[].composition.status- Matching observed snapshots, unresolved changes or missing coverage.One of
observed_stable,mixed,unknown facts.rows[].composition.validFrom- Inferred start of a fully bracketed account-local day; not an exact provider change time.
facts.rows[].composition.validUntil- Inferred exclusive end of that bracketed day.
facts.rows[].currency- Reported account currency.
facts.rows[].datefacts.rows[].denominators- Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
facts.rows[].fetchedAt- When this latest stored provider fact was fetched; not a point-in-time training snapshot.
facts.rows[].metrics- Provider ad/day metrics as decimal strings (with video plays, 100% plays, average watch time in seconds and unique clicks); null stays unknown. Daily reach and unique clicks are not additive.
facts.rows[].rankings- Meta's rankings of the ad that day: quality, engagementRate, conversionRate (ABOVE_AVERAGE, AVERAGE, BELOW_AVERAGE_35, BELOW_AVERAGE_20, BELOW_AVERAGE_10, UNKNOWN); absent when Meta gave none.
facts.rows[].resultIndicator- Provider result indicator, when reported.
facts.rows[].timezone- Reported account timezone used for the day.
facts.sincefacts.untilfactsFingerprint- Hash of the exact preserved facts.
groupAdIdsid- Immutable observed outcome ID.
inference- One of
descriptive_only limitations- Sample, allocation, stopping and composition caveats.
note- Recorded capture reason.
observedAt- Snapshot capture time.
until- Captured end day.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The design version changed, a group has no registered delivery ad, or the experiment was canceled.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26/outcomes" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2022b11d-06df-4303-a30d-002ed7c1f0a3" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"until": "2026-09-27"
}'Change a creative experiment's status
Registered to running or cancelled; running to completed or cancelled. An administrative record only: it controls no campaign or delivery.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The experiment's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
reason- Reason for the state transition.
status- Allowed transitions: registered to running/cancelled; running to completed/cancelled.One of
registered,running,completed,cancelled
Response
createdAt- First registration.
currentVersion- Latest immutable design version.
firstAssessedAt- Earliest Pluto outcome-read attempt; retained even if reading failed.
id- Experiment ID.
revisionrevision.actorId- Declaring actor.
revision.actorKind- Actor category.One of
person,api_key,agent,system revision.amendmentReason- Why an immutable revision was appended.
revision.designrevision.design.allocationrevision.design.allocation.interferencePolicy- How repeated exposure, spillover and overlap are handled.
revision.design.allocation.method- Declared design; actual execution is not independently verified.One of
randomized,quasi_experimental,observational revision.design.allocation.procedure- Document assignment mechanism and planned allocation.
revision.design.allocation.provenancerevision.design.allocation.unit- Experimental unit, not the reported aggregation level.One of
person,household,geography,campaign,ad_set,ad,time_block revision.design.allocation.unitDefinition- Define the eligible experimental unit and population.
revision.design.counterarguments- Alternative explanations that may falsify the hypothesis.
revision.design.creativeChange- The planned intervention and what differs.
revision.design.creativeChangeIsolated- A declaration of isolation, not a verified claim.
revision.design.groupsrevision.design.groups[].allocationShare- Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesrevision.design.groups[].keyrevision.design.groups[].name- Comparison group name.
revision.design.groups[].role- Exactly one control.One of
control,treatment revision.design.heldConstant- Conditions intended to remain equal.
revision.design.hypothesis- Falsifiable hypothesis recorded before results.
revision.design.knownConfounders- Known differences that limit attribution.
revision.design.name- Experiment name.
revision.design.primaryMetricrevision.design.primaryMetric.attribution- Exact provider attribution window.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click revision.design.primaryMetric.definition- Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.primaryMetric.direction- Prespecified desired direction.One of
increase,decrease revision.design.primaryMetric.numerator- Original provider ad/day metric; unknown values remain null.One of
spend,impressions,reach,clicks,linkClicks,landingPageViews,addToCart,initiateCheckout,purchases,purchaseValue,videoViews,thruplays,results,leads,outboundClicks,videoP25,videoP50,videoP75,videoP95 revision.design.stoppingRulerevision.design.stoppingRule.kind- One of
sequential revision.design.stoppingRule.minimumUnitsPerGroup- Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRule- Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksrevision.design.stoppingRule.schedule- Prespecified analysis schedule.
revision.design.windowrevision.design.window.currency- Accepted ISO currency matching all enrolled accounts.
revision.design.window.since- Inclusive first account-local day.
revision.design.window.timezone- IANA timezone matching all enrolled accounts.
revision.design.window.until- Inclusive last day; at most 31 days.
revision.experimentId- Experiment ID.
revision.fingerprint- Versioned immutable design and source fingerprint.
revision.limitations- Design and causal-inference limitations.
revision.preregistered- This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeen- Registrant's current attestation.
revision.registeredAt- Server registration time.
revision.registrationTiming- Server-calculated temporal qualification.One of
prospective,historical_window,prior_results_declared,amendment_after_assessment,amendment_after_start revision.schemaVersion- Design contract version.
revision.sources- Source-backed comparison groups.
revision.sources[].creatives- Exact server-resolved revisions.
revision.sources[].creatives[].assets- Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextrevision.sources[].creatives[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryrevision.sources[].groupKey- Registered comparison group.
revision.version- Immutable design version.
status- Current administrative status; not an inference result.One of
registered,running,completed,cancelled updatedAt- Latest administrative change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The version changed or the transition is not available.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 63247758-760f-4582-8177-ec1d6b50becc" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"reason": "Spend is pacing ahead of plan; hold the budget until Friday.",
"status": "registered"
}'List library imports
Explicit historical basic-index imports, newest first, with progress joined from each accepted child request.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | The previous page's nextAfter. |
limit | string | Optional | Page size, 1 to 100 (default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].changesPending- Coalesced source-change notifications still awaiting discovery.
items[].createdAt- Creation time.
items[].cursorId- Last enumerated media ID.
items[].id- Durable parent ID.
items[].jobId- Current parent job in Activity.
items[].progressitems[].progress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.failed- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.partial- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.pending- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.queued- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.ready- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.running- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
items[].progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
items[].reason- Pause or cancellation explanation.
items[].scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
items[].scopeitems[].scope.kind- Only these media IDs.One of
selected items[].scope.mediaIds- Explicit fixed media selection.
items[].status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled items[].updatedAt- Latest parent checkpoint or control time.
items[].watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
items[].watermarkId- Inclusive media-ID boundary.
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/imports" \
-H "Authorization: Bearer $PLUTO_KEY"Start a library import
Starts one durable basic-index import of all media at a pinned creation cutoff, or of 1 to 1,000 selected media. Media added later are not part of it. Each child is an ordinary index request with its own included-allowance reservation; an import never uses credits or overage. One import is active per workspace; repeating the same scope returns it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402The organization is read-only.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Another import with a different scope is active.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7d931722-afee-4f73-ba03-91a1187213a0" \
-H "Content-Type: application/json" \
-d '{
"scope": {
"kind": "all"
}
}'Read a library import
Scope, cutoff, scan cursor and progress. Children already accepted keep their real status after the import pauses or stops; a child whose request is gone reads as unavailable, never ready.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0" \
-H "Authorization: Bearer $PLUTO_KEY"Stop a library import
Stops new submissions for good. Accepted children keep running and are reported as they are; cancel a child request to stop it. Works while the organization is read-only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/cancel" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a9eb8796-9f77-45f8-b780-e29cdf4b4833"List library import items
Each media source revision and attempt the import considered, with its child request and status. A retried attempt keeps the earlier attempt and its receipt.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
after | string | Optional | The previous page's nextAfter. |
limit | string | Optional | Page size, 1 to 100 (default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].attempt- Zero-based attempt for this source revision.
items[].id- Revision attempt ID.
items[].mediaId- Original media ID, retained even if deleted.
items[].reason- Skip or child failure explanation.
items[].requestId- Ordinary Creative Memory child; null before acceptance or if its record was removed.
items[].sourceRevision- Immutable source fingerprint; unavailable observations have their own fingerprint.
items[].status- Actual child status when accepted; no inferred success.One of
pending,queued,running,ready,partial,failed,cancelled,skipped,unavailable items[].superseded- An explicit retry superseded this attempt; its child receipt remains intact.
nextAfter- 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.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/items" \
-H "Authorization: Bearer $PLUTO_KEY"Retry a library import item
Queues a new attempt for a failed or canceled child with a fresh reservation. The earlier attempt and its receipt stay in the history.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
itemId | string | Required | The item's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402The organization is read-only.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Only a failed or canceled child can be retried, and not on a stopped import.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/items/5759e82a-759b-4fb8-bfdc-8170258b64dd/retry" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5cfd1fb4-3160-4149-802d-17fb482fcbce"Pause a library import
Stops new submissions at the current checkpoint; accepted children continue. Works while the organization is read-only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/pause" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8d39501f-9778-4bc6-aa3d-9abef29f388e"Resume a library import
Continues a paused import from its checkpoint, including one paused because the included allowance ran out.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The import's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
changesPending- Coalesced source-change notifications still awaiting discovery.
createdAt- Creation time.
cursorId- Last enumerated media ID.
id- Durable parent ID.
jobId- Current parent job in Activity.
progressprogress.cancelled- Revision attempts in this state; superseded retries are kept in item history.
progress.discovered- Revision attempts in this state; superseded retries are kept in item history.
progress.failed- Revision attempts in this state; superseded retries are kept in item history.
progress.partial- Revision attempts in this state; superseded retries are kept in item history.
progress.pending- Revision attempts in this state; superseded retries are kept in item history.
progress.queued- Revision attempts in this state; superseded retries are kept in item history.
progress.ready- Revision attempts in this state; superseded retries are kept in item history.
progress.running- Revision attempts in this state; superseded retries are kept in item history.
progress.skipped- Revision attempts in this state; superseded retries are kept in item history.
progress.unavailable- Revision attempts in this state; superseded retries are kept in item history.
reason- Pause or cancellation explanation.
scanComplete- Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopescope.kind- Only these media IDs.One of
selected scope.mediaIds- Explicit fixed media selection.
status- Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of
running,paused,completed,cancelled updatedAt- Latest parent checkpoint or control time.
watermarkAt- Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkId- Inclusive media-ID boundary.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402The organization is read-only.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The import is finished.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/resume" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: db641cc6-b9cd-4661-8896-4ca1a5d16701"List learning labels
Explicit content-accuracy, query-relevance and user-utility annotations, newest first. They are unverified judgments, separate from corrections and ad outcomes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
mediaId | string | Optional | Optional media filter. |
after | string | Optional | Previous nextAfter ID. |
limit | string | Optional | 1–100, default 40. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].actorId- Recorded actor.
items[].actorKind- Actual actor, never assumed to be human.One of
person,api_key,agent,system items[].assetId- Exact verified source.
items[].createdAt- Server recording time.
items[].evidenceitems[].evidence.endMs- Original-media end.
items[].evidence.id- Raw evidence or immutable correction ID.
items[].evidence.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
items[].evidence.publicationId- Effective publication source.
items[].evidence.source- Original evidence modality.
items[].evidence.sourceRef- Original or conflict-qualified source reference.
items[].evidence.startMs- Original-media start.
items[].evidence.text- Recorded text.
items[].id- Immutable annotation.
items[].inputitems[].input.annotationitems[].input.annotation.evidenceId- Optional particular evidence.
items[].input.annotation.kind- One of
user_utility items[].input.annotation.verdict- Explicit utility judgment; no automatic label from a click.One of
useful,not_useful,uncertain items[].input.annotation.query- Explicit query whose relevance is judged.
items[].input.provenanceitems[].input.provenance.auditIdsitems[].input.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity items[].input.provenance.note- Document how this relationship or allocation is known.
items[].input.provenance.referencesitems[].input.rationale- Reason for the explicit annotation.
items[].input.snapshotitems[].input.snapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
items[].input.snapshot.expectedPublicationIdsitems[].input.snapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
items[].input.snapshot.mediaId- Exact source media.
items[].input.supersedesId- Latest label being corrected; history remains immutable.
items[].limitations- Label stream and truth constraints.
items[].origin- One of
explicit_annotation items[].schemaVersion- Label contract version.
items[].verifierStatus- One of
unverified nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/labels" \
-H "Authorization: Bearer $PLUTO_KEY"Record a learning label
Appends one annotation for the reviewed snapshot; supersedesId amends the latest label of the same stream. Labels never edit evidence, train a model or change a threshold.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
annotationannotation.evidenceId- Optional particular evidence.
annotation.kind- One of
user_utility annotation.verdict- Explicit utility judgment; no automatic label from a click.One of
useful,not_useful,uncertain annotation.query- Explicit query whose relevance is judged.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationale- Reason for the explicit annotation.
snapshotsnapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdssnapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
snapshot.mediaId- Exact source media.
supersedesId- Latest label being corrected; history remains immutable.
Response
actorId- Recorded actor.
actorKind- Actual actor, never assumed to be human.One of
person,api_key,agent,system assetId- Exact verified source.
createdAt- Server recording time.
evidenceevidence.endMs- Original-media end.
evidence.id- Raw evidence or immutable correction ID.
evidence.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence.publicationId- Effective publication source.
evidence.source- Original evidence modality.
evidence.sourceRef- Original or conflict-qualified source reference.
evidence.startMs- Original-media start.
evidence.text- Recorded text.
id- Immutable annotation.
inputinput.annotationinput.annotation.evidenceId- Optional particular evidence.
input.annotation.kind- One of
user_utility input.annotation.verdict- Explicit utility judgment; no automatic label from a click.One of
useful,not_useful,uncertain input.annotation.query- Explicit query whose relevance is judged.
input.provenanceinput.provenance.auditIdsinput.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity input.provenance.note- Document how this relationship or allocation is known.
input.provenance.referencesinput.provenance.references[].observedAt- When the declarer observed this source, no future dates.
input.provenance.references[].title- Source document title.
input.provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.rationale- Reason for the explicit annotation.
input.snapshotinput.snapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
input.snapshot.expectedPublicationIdsinput.snapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
input.snapshot.mediaId- Exact source media.
input.supersedesId- Latest label being corrected; history remains immutable.
limitations- Label stream and truth constraints.
origin- One of
explicit_annotation schemaVersion- Label contract version.
verifierStatus- One of
unverified
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409The snapshot changed, or the superseded label is not the latest in its stream.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/labels" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b53bc2a2-02b9-401f-be6b-ee6227ac06b8" \
-H "Content-Type: application/json" \
-d '{
"annotation": {
"evidenceId": "a20a2bd4-3cb6-4cf5-b44f-8ad205039b40",
"kind": "content_accuracy",
"verdict": "supported"
},
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"rationale": "Spend is pacing ahead of plan; hold the budget until Friday.",
"snapshot": {
"expectedCorrectionId": "be793c5e-2d9d-4e66-acae-709a7c022109",
"expectedPublicationIds": [
"a4611f0e-475f-48e8-851b-59c1f6844ffb"
],
"expectedSourceFingerprint": "1c70088ea7663d97",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
},
"supersedesId": "324d5504-a494-4263-bc3a-1d1fdda8cb1d"
}'Read a learning label
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The label's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
actorId- Recorded actor.
actorKind- Actual actor, never assumed to be human.One of
person,api_key,agent,system assetId- Exact verified source.
createdAt- Server recording time.
evidenceevidence.endMs- Original-media end.
evidence.id- Raw evidence or immutable correction ID.
evidence.provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence.publicationId- Effective publication source.
evidence.source- Original evidence modality.
evidence.sourceRef- Original or conflict-qualified source reference.
evidence.startMs- Original-media start.
evidence.text- Recorded text.
id- Immutable annotation.
inputinput.annotationinput.annotation.evidenceId- Optional particular evidence.
input.annotation.kind- One of
user_utility input.annotation.verdict- Explicit utility judgment; no automatic label from a click.One of
useful,not_useful,uncertain input.annotation.query- Explicit query whose relevance is judged.
input.provenanceinput.provenance.auditIdsinput.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity input.provenance.note- Document how this relationship or allocation is known.
input.provenance.referencesinput.provenance.references[].observedAt- When the declarer observed this source, no future dates.
input.provenance.references[].title- Source document title.
input.provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.rationale- Reason for the explicit annotation.
input.snapshotinput.snapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
input.snapshot.expectedPublicationIdsinput.snapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
input.snapshot.mediaId- Exact source media.
input.supersedesId- Latest label being corrected; history remains immutable.
limitations- Label stream and truth constraints.
origin- One of
explicit_annotation schemaVersion- Label contract version.
verifierStatus- One of
unverified
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/labels/3b3e38bc-b355-4d75-a044-270c99d48ced" \
-H "Authorization: Bearer $PLUTO_KEY"List recorded creative relationships
Current (not superseded) variant and family claims with their pinned source revisions. Similarity never confirms a relationship.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Previous nextAfter record ID. |
limit | string | Optional | 1–100, default 40. |
fingerprint | string | Optional | Only claims naming this exact recorded revision fingerprint. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].actorId- Recorded actor.
items[].actorKind- Actor category.One of
person,api_key,agent,system items[].createdAt- Server recording time.
items[].id- Immutable relationship record.
items[].inputitems[].input.amendmentReason- Required when superseding a record.
items[].input.provenanceitems[].input.provenance.auditIdsitems[].input.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity items[].input.provenance.note- Document how this relationship or allocation is known.
items[].input.provenance.referencesitems[].input.recorditems[].input.record.changedComponentsitems[].input.record.childitems[].input.record.familyId- Optional exact recorded family containing both revisions.
items[].input.record.kind- One of
family items[].input.record.parentitems[].input.record.relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation items[].input.record.description- Documented basis for membership.
items[].input.record.membersitems[].input.record.name- Family name.
items[].input.status- Confirmation requires declared or recorded provenance; never similarity alone.One of
candidate,confirmed,rejected items[].input.supersedesId- Latest record to amend; historical records remain available.
items[].limitations- Explicit interpretation limits.
items[].schemaVersion- Creative lineage contract version.
items[].sources- Exact server-resolved source revisions.
items[].sources[].assets- Verified source revisions, no bucket keys or signed URLs.
items[].sources[].assets[].byteSize- Verified source byte size.
items[].sources[].assets[].durationMs- Original video duration, null for images.
items[].sources[].assets[].kind- Media kind.
items[].sources[].assets[].mediaId- Pinned source media.
items[].sources[].assets[].sha256- Verified original bytes hash.
items[].sources[].assets[].sourceFingerprint- Exact asset revision fingerprint.
items[].sources[].contextitems[].sources[].context.assetsComplete- Whether the complete media composition is known.
items[].sources[].context.copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
items[].sources[].context.copyComplete- Whether all advertiser-supplied copy is represented.
items[].sources[].context.fingerprint- Version of this exact composition and source media.
items[].sources[].context.limitations- Why some composition or evidence remains unknown.
items[].sources[].context.mediaIds- Media available for evidence lookup.
items[].sources[].context.name- Creative name.
items[].sources[].context.observedAt- When this composition was observed.
items[].sources[].context.source- Draft, media or a recorded published Meta snapshot/readback.
items[].sources[].context.subjectitems[].sources[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
items[].sources[].deliveryitems[].sources[].delivery.adAccountId- Source account.
items[].sources[].delivery.adId- Observed Meta ad ID.
items[].sources[].delivery.creativeId- Observed Meta creative ID, null when unavailable.
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/lineage" \
-H "Authorization: Bearer $PLUTO_KEY"Record a creative relationship
Records a variant or family claim against exact reviewed revisions with documented provenance. Similarity can only suggest a candidate. Amend with supersedesId and a reason; history stays retrievable. No media, campaign or analysis changes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
amendmentReason- Required when superseding a record.
provenanceprovenance.auditIdsprovenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity provenance.note- Document how this relationship or allocation is known.
provenance.referencesprovenance.references[].observedAt- When the declarer observed this source, no future dates.
provenance.references[].title- Source document title.
provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
recordrecord.changedComponentsrecord.childrecord.child.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
record.child.subjectrecord.child.subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad record.child.subject.mediaId- Media in this workspace.
record.child.subject.adId- Meta ad ID.
record.child.subject.adAccountId- Optional Meta ad account ID.
record.familyId- Optional exact recorded family containing both revisions.
record.kind- One of
family record.parentrecord.parent.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
record.parent.subjectrecord.parent.subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad record.parent.subject.mediaId- Media in this workspace.
record.parent.subject.adId- Meta ad ID.
record.parent.subject.adAccountId- Optional Meta ad account ID.
record.relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation record.description- Documented basis for membership.
record.membersrecord.members[].expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
record.members[].subjectrecord.members[].subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad record.members[].subject.mediaId- Media in this workspace.
record.members[].subject.adId- Meta ad ID.
record.members[].subject.adAccountId- Optional Meta ad account ID.
record.name- Family name.
status- Confirmation requires declared or recorded provenance; never similarity alone.One of
candidate,confirmed,rejected supersedesId- Latest record to amend; historical records remain available.
Response
actorId- Recorded actor.
actorKind- Actor category.One of
person,api_key,agent,system createdAt- Server recording time.
id- Immutable relationship record.
inputinput.amendmentReason- Required when superseding a record.
input.provenanceinput.provenance.auditIdsinput.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity input.provenance.note- Document how this relationship or allocation is known.
input.provenance.referencesinput.provenance.references[].observedAt- When the declarer observed this source, no future dates.
input.provenance.references[].title- Source document title.
input.provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.recordinput.record.changedComponentsinput.record.childinput.record.child.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.child.subjectinput.record.familyId- Optional exact recorded family containing both revisions.
input.record.kind- One of
family input.record.parentinput.record.parent.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.parent.subjectinput.record.relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation input.record.description- Documented basis for membership.
input.record.membersinput.record.members[].expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.members[].subjectinput.record.name- Family name.
input.status- Confirmation requires declared or recorded provenance; never similarity alone.One of
candidate,confirmed,rejected input.supersedesId- Latest record to amend; historical records remain available.
limitations- Explicit interpretation limits.
schemaVersion- Creative lineage contract version.
sources- Exact server-resolved source revisions.
sources[].assets- Verified source revisions, no bucket keys or signed URLs.
sources[].assets[].byteSize- Verified source byte size.
sources[].assets[].durationMs- Original video duration, null for images.
sources[].assets[].kind- Media kind.
sources[].assets[].mediaId- Pinned source media.
sources[].assets[].sha256- Verified original bytes hash.
sources[].assets[].sourceFingerprint- Exact asset revision fingerprint.
sources[].contextsources[].context.assetsComplete- Whether the complete media composition is known.
sources[].context.copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
sources[].context.copyComplete- Whether all advertiser-supplied copy is represented.
sources[].context.fingerprint- Version of this exact composition and source media.
sources[].context.limitations- Why some composition or evidence remains unknown.
sources[].context.mediaIds- Media available for evidence lookup.
sources[].context.name- Creative name.
sources[].context.observedAt- When this composition was observed.
sources[].context.source- Draft, media or a recorded published Meta snapshot/readback.
sources[].context.subjectsources[].context.subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad sources[].context.subject.mediaId- Media in this workspace.
sources[].context.subject.adId- Meta ad ID.
sources[].context.subject.adAccountId- Optional Meta ad account ID.
sources[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
sources[].deliverysources[].delivery.adAccountId- Source account.
sources[].delivery.adId- Observed Meta ad ID.
sources[].delivery.creativeId- Observed Meta creative ID, null when unavailable.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409A creative changed since it was reviewed, or the record was already amended.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/lineage" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 52fcc62f-828a-4139-bf80-e57bfea56495" \
-H "Content-Type: application/json" \
-d '{
"amendmentReason": null,
"provenance": {
"auditIds": [
"4626ee3b-89fd-460c-b4ff-0aa48a1a65f4"
],
"basis": "creator_declaration",
"note": "Spend is pacing ahead of plan; hold the budget until Friday.",
"references": [
{
"observedAt": "2026-09-26T09:30:00Z",
"title": "Vitamin C Serum, UGC 9x16",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
]
},
"record": {
"changedComponents": [
"hook"
],
"child": {
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {
"kind": "media",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}
},
"familyId": "11ac9ffb-f37a-4cbd-8263-b5cf0f9e32be",
"kind": "variant",
"parent": {
"expectedFingerprint": "381c6ba792b4fefc",
"subject": {
"kind": "media",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
}
},
"relationship": "derived_from"
},
"status": "candidate",
"supersedesId": "324d5504-a494-4263-bc3a-1d1fdda8cb1d"
}'Read a recorded creative relationship
Reads one immutable claim, current or superseded, with its declarer and pinned source revisions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The lineage's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
actorId- Recorded actor.
actorKind- Actor category.One of
person,api_key,agent,system createdAt- Server recording time.
id- Immutable relationship record.
inputinput.amendmentReason- Required when superseding a record.
input.provenanceinput.provenance.auditIdsinput.provenance.basis- Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of
creator_declaration,workflow_record,similarity input.provenance.note- Document how this relationship or allocation is known.
input.provenance.referencesinput.provenance.references[].observedAt- When the declarer observed this source, no future dates.
input.provenance.references[].title- Source document title.
input.provenance.references[].url- Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.recordinput.record.changedComponentsinput.record.childinput.record.child.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.child.subjectinput.record.familyId- Optional exact recorded family containing both revisions.
input.record.kind- One of
family input.record.parentinput.record.parent.expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.parent.subjectinput.record.relationship- Declared relationship, not inferred causality.One of
derived_from,translation,edit,shared_concept,controlled_variation input.record.description- Documented basis for membership.
input.record.membersinput.record.members[].expectedFingerprint- Exact current context fingerprint; changes cause a conflict.
input.record.members[].subjectinput.record.name- Family name.
input.status- Confirmation requires declared or recorded provenance; never similarity alone.One of
candidate,confirmed,rejected input.supersedesId- Latest record to amend; historical records remain available.
limitations- Explicit interpretation limits.
schemaVersion- Creative lineage contract version.
sources- Exact server-resolved source revisions.
sources[].assets- Verified source revisions, no bucket keys or signed URLs.
sources[].assets[].byteSize- Verified source byte size.
sources[].assets[].durationMs- Original video duration, null for images.
sources[].assets[].kind- Media kind.
sources[].assets[].mediaId- Pinned source media.
sources[].assets[].sha256- Verified original bytes hash.
sources[].assets[].sourceFingerprint- Exact asset revision fingerprint.
sources[].contextsources[].context.assetsComplete- Whether the complete media composition is known.
sources[].context.copy- Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
sources[].context.copyComplete- Whether all advertiser-supplied copy is represented.
sources[].context.fingerprint- Version of this exact composition and source media.
sources[].context.limitations- Why some composition or evidence remains unknown.
sources[].context.mediaIds- Media available for evidence lookup.
sources[].context.name- Creative name.
sources[].context.observedAt- When this composition was observed.
sources[].context.source- Draft, media or a recorded published Meta snapshot/readback.
sources[].context.subjectsources[].context.subject.kind- Observed published Meta ad; never substitute its current draft.One of
meta_ad sources[].context.subject.mediaId- Media in this workspace.
sources[].context.subject.adId- Meta ad ID.
sources[].context.subject.adAccountId- Optional Meta ad account ID.
sources[].creativeRevisionId- Persisted ad composition revision; null for standalone media.
sources[].deliverysources[].delivery.adAccountId- Source account.
sources[].delivery.adId- Observed Meta ad ID.
sources[].delivery.creativeId- Observed Meta creative ID, null when unavailable.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/lineage/170c7a35-b7fa-460f-b737-efe61fb64178" \
-H "Authorization: Bearer $PLUTO_KEY"Read creative evidence and coverage
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
automaticAnalysisautomaticAnalysis.renewsAt- When the included credits reset, with waiting_for_allowance.
automaticAnalysis.status- when_used_in_ad: in no ad yet; analyzed once an ad with it goes live. starting: starts once the file is searchable. waiting_for_allowance: starts when the organization has credits again (included credits reset on the 1st, or more are bought). too_long: too long to analyze in one go; request a section instead.One of
when_used_in_ad,starting,waiting_for_allowance,too_long coveragecoverage.description- What was and was not examined.
coverage.status- Readiness/coverage status.
evidence- Cited observations, preserving source timestamps.
evidence[].endMs- Original-media end.
evidence[].id- Source reference.
evidence[].origin- Omitted for recorded model evidence. authorized_correction: a reviewed human correction, an attributed assertion rather than verified truth. revalidation_required: an observation that disagrees with an active correction; it cannot prove a condition.One of
authorized_correction,revalidation_required evidence[].source- Evidence modality/source.
evidence[].startMs- Original-media start.
evidence[].text- Observed evidence.
mediaId- Media.
requests- Processing requests.
requests[].createdAt- Accepted.
requests[].error- Actionable failure, if any.
requests[].id- Request.
requests[].items- Selected media and original-media sections.
requests[].items[].endMs- Optional exclusive section end in original-media milliseconds.
requests[].items[].mediaId- Media in this workspace.
requests[].items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
requests[].jobId- Durable job; use get_job or wait_for_job.
requests[].kind- Processing requested.One of
index,deep requests[].status- Current execution state, independent of published coverage.
requests[].units- New analysis units: 50 credits each (an image; a started video minute is 5).
status- Available in-depth readiness.
summary- Published interpretation.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/media/04acd56b-ded4-4670-9f9b-1c0c550c1701" \
-H "Authorization: Bearer $PLUTO_KEY"Read correctable evidence
The exact reviewed snapshot to send with a correction or label (source fingerprint, every current publication and the correction head), up to 500 effective evidence entries with provenance, edited and conflict state, active patches and a bounded preview of corrections kept for other source versions. Starts no processing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The media's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
activePatchIds- Read correction history by these IDs to revise a retracted observation.
assetId- Verified source revision.
conflicted- A later raw baseline requires explicit revalidation.
edited- An active manual overlay exists.
evidence- At most 500 effective source-linked documents.
evidence[].endMs- Original-media end.
evidence[].id- Raw evidence or immutable correction ID.
evidence[].provenance- Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence[].publicationId- Effective publication source.
evidence[].source- Original evidence modality.
evidence[].sourceRef- Original or conflict-qualified source reference.
evidence[].startMs- Original-media start.
evidence[].text- Recorded text.
evidenceTruncated- More evidence exists beyond this bounded preview.
historicalCorrectionIds- At most 50 recent historical revisions requiring explicit rebase.
limitations- Origin and coverage constraints.
snapshotsnapshot.expectedCorrectionId- Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIds- Reviewed active publications; empty while the media has none.
snapshot.expectedSourceFingerprint- Reviewed current source fingerprint.
snapshot.mediaId- Exact source media.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/media/04acd56b-ded4-4670-9f9b-1c0c550c1701/correction-context" \
-H "Authorization: Bearer $PLUTO_KEY"List creative monitor coverage
Coverage runs of creative monitor steps in loops, newest first. Each describes the scope, membership cutoff, change sequence and counts of one loop run; guests can't read them.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
loopId | string | Optional | Only coverage runs of this loop. |
after | string | Optional | The previous page's nextAfter. |
limit | string | Optional | Page size, 1 to 100 (default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Coverage runs.
items[].actionLimit- Maximum matching subjects passed to ordinary Loop branches.
items[].actionsLimited- Known matches not offered because the bounded action selection excluded them.
items[].completedAt- Coverage completion time, absent for incomplete or canceled evaluation.
items[].config- Pinned scope, condition, predicateVersion, quantifier and actionLimit from the Loop version.
items[].currentSequence- Current workspace change sequence; newer means coverage may be stale.
items[].enumerationComplete- All subjects in scope and captured changes were enumerated.
items[].evaluationComplete- Every enumerated subject reached an explicit result; this does not mean every result is known or every action ran.
items[].fresh- No newer recorded dependency notification exists.
items[].id- Coverage run ID.
items[].loopId- Owning saved Loop.
items[].loopRunId- Existing Loop job/run ID.
items[].loopVersion- Immutable approved definition version.
items[].membersAfter- For a later run, the previous run's cutoff: subjects that appeared after it and by watermarkAt are this run's new members. Null for a complete enumeration.
items[].runCountsitems[].runCounts.deleted- Subject count in this state; unknown is never false.
items[].runCounts.failed- Subject count in this state; unknown is never false.
items[].runCounts.knownFalse- Subject count in this state; unknown is never false.
items[].runCounts.knownTrue- Subject count in this state; unknown is never false.
items[].runCounts.missing- Subject count in this state; unknown is never false.
items[].runCounts.pending- Subject count in this state; unknown is never false.
items[].runCounts.total- Subject count in this state; unknown is never false.
items[].runCounts.unknown- Subject count in this state; unknown is never false.
items[].scopeCountsitems[].scopeCounts.deleted- Subject count in this state; unknown is never false.
items[].scopeCounts.failed- Subject count in this state; unknown is never false.
items[].scopeCounts.knownFalse- Subject count in this state; unknown is never false.
items[].scopeCounts.knownTrue- Subject count in this state; unknown is never false.
items[].scopeCounts.missing- Subject count in this state; unknown is never false.
items[].scopeCounts.pending- Subject count in this state; unknown is never false.
items[].scopeCounts.total- Subject count in this state; unknown is never false.
items[].scopeCounts.unknown- Subject count in this state; unknown is never false.
items[].selected- Subjects offered to normal Loop execution, not completed actions.
items[].status- Owning Loop execution status, including cancelled and failed.
items[].stepId- Saved creative-monitor step.
items[].throughSequence- Content change sequence incorporated into this run.
items[].watermarkAt- Membership cutoff: only subjects that existed at this time belong to this run; later subjects wait for a later run.
nextAfter- Next cursor.
curl "$PLUTO_API/creative-memory/monitors" \
-H "Authorization: Bearer $PLUTO_KEY"Read creative monitor coverage
One coverage run: membership cutoff, whether enumeration and evaluation finished, freshness against later content changes, whole-scope and run counts of true, false, unknown, pending, missing, deleted and failed subjects, and how many matches were offered to the loop's next steps or held back by the action limit. Offered is not a claim that an action happened.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The monitor's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
actionLimit- Maximum matching subjects passed to ordinary Loop branches.
actionsLimited- Known matches not offered because the bounded action selection excluded them.
completedAt- Coverage completion time, absent for incomplete or canceled evaluation.
config- Pinned scope, condition, predicateVersion, quantifier and actionLimit from the Loop version.
currentSequence- Current workspace change sequence; newer means coverage may be stale.
enumerationComplete- All subjects in scope and captured changes were enumerated.
evaluationComplete- Every enumerated subject reached an explicit result; this does not mean every result is known or every action ran.
fresh- No newer recorded dependency notification exists.
id- Coverage run ID.
loopId- Owning saved Loop.
loopRunId- Existing Loop job/run ID.
loopVersion- Immutable approved definition version.
membersAfter- For a later run, the previous run's cutoff: subjects that appeared after it and by watermarkAt are this run's new members. Null for a complete enumeration.
runCountsrunCounts.deleted- Subject count in this state; unknown is never false.
runCounts.failed- Subject count in this state; unknown is never false.
runCounts.knownFalse- Subject count in this state; unknown is never false.
runCounts.knownTrue- Subject count in this state; unknown is never false.
runCounts.missing- Subject count in this state; unknown is never false.
runCounts.pending- Subject count in this state; unknown is never false.
runCounts.total- Subject count in this state; unknown is never false.
runCounts.unknown- Subject count in this state; unknown is never false.
scopeCountsscopeCounts.deleted- Subject count in this state; unknown is never false.
scopeCounts.failed- Subject count in this state; unknown is never false.
scopeCounts.knownFalse- Subject count in this state; unknown is never false.
scopeCounts.knownTrue- Subject count in this state; unknown is never false.
scopeCounts.missing- Subject count in this state; unknown is never false.
scopeCounts.pending- Subject count in this state; unknown is never false.
scopeCounts.total- Subject count in this state; unknown is never false.
scopeCounts.unknown- Subject count in this state; unknown is never false.
selected- Subjects offered to normal Loop execution, not completed actions.
status- Owning Loop execution status, including cancelled and failed.
stepId- Saved creative-monitor step.
throughSequence- Content change sequence incorporated into this run.
watermarkAt- Membership cutoff: only subjects that existed at this time belong to this run; later subjects wait for a later run.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/monitors/a420a2bb-d624-48aa-983b-889dc97f0067" \
-H "Authorization: Bearer $PLUTO_KEY"List creative monitor items
The subjects this run examined, with truth, evaluation state, evidence summary and selection (offered, unchanged, limited, no action), joined with the loop item's actual outcome.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The monitor's ID. |
after | string | Optional | The previous page's nextAfter (a subject ID). |
limit | string | Optional | Page size, 1 to 100 (default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This run's evaluated or pending subjects; older unchanged scope results remain in scopeCounts.
items[].actionOutcome- Existing Loop item outcome; null is not success.
items[].changed- Relevant dependencies changed since the monitor's prior result.
items[].dependencyHash- Normalized content, correction and predicate identity; vectors are excluded.
items[].evaluation- Recorded-evidence result and limitations.
items[].execution- Selection for ordinary Loop execution, independently of predicate truth.One of
not_selected,offered,unchanged,limited,no_action items[].observedAt- Last successful evaluation/reuse time.
items[].state- Evaluation execution state.One of
pending,evaluated,missing,deleted,failed items[].subject- Explicit media, draft ad or Meta ad subject.
items[].subjectId- Stable scoped subject ID.
items[].value- Predicate truth; null means still pending.One of
true,false,unknown nextAfter- Next subject cursor.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/monitors/a420a2bb-d624-48aa-983b-889dc97f0067/items" \
-H "Authorization: Bearer $PLUTO_KEY"Read creative performance evidence
Read 1–100 distinct Meta ads over at most 31 inclusive account-local days for an explicit attribution window. Preserves provider ad/day facts, currency, timezone, denominators and fetch time. Composition is observed_stable, mixed or unknown; matching snapshots only assume continuity. Missing days are omitted and null metrics stay unknown. Outcomes are never duplicated or allocated to assets. No fetching, inference or causal attribution runs.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
adIds- Distinct requested ads; outcomes remain at ad/day level.
attribution- Exact provider attribution window; no windows are added together.One of
7d_click_1d_view,7d_click,1d_click,1d_view,28d_click since- Inclusive account-local first date (YYYY-MM-DD).
until- Inclusive account-local last date; at most 31 days total.
Response
attribution- Requested provider attribution window.
limitations- Coverage, observation, delivery and causal limitations.
maxBracketHours- Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
missingAdIds- Missing days and metrics are not zero-filled.
requestedAdIds- Requested ads.
retrievedAt- When Pluto assembled this read.
rows- Original ad/day facts; outcomes are never duplicated or allocated to each asset.
rows[].actionValues- The value of each action type, in the account currency.
rows[].actions- Every action type Meta counted that day in the attribution window, by Meta's action type (omni_purchase, lead, post_reaction, offsite_conversion.custom.<id>, …); absent: not reported.
rows[].adAccountId- Source Meta ad account.
rows[].adId- Source Meta ad.
rows[].adsetId- Reported ad set.
rows[].attribution- Exact provider attribution window.
rows[].campaignId- Reported campaign.
rows[].compositionrows[].composition.assumedContinuity- True means matching snapshots assume continuity; intermediate changes were not observed.
rows[].composition.creativeId- Only set for an observed stable bracket; not a delivered dynamic asset ID.
rows[].composition.firstObservedAt- Earliest supporting observation time.
rows[].composition.lastObservedAt- Latest supporting observation time.
rows[].composition.observationCount- Supporting observations.
rows[].composition.reason- Why composition is stable, mixed or unknown.
rows[].composition.status- Matching observed snapshots, unresolved changes or missing coverage.One of
observed_stable,mixed,unknown rows[].composition.validFrom- Inferred start of a fully bracketed account-local day; not an exact provider change time.
rows[].composition.validUntil- Inferred exclusive end of that bracketed day.
rows[].currency- Reported account currency.
rows[].daterows[].denominators- Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
rows[].fetchedAt- When this latest stored provider fact was fetched; not a point-in-time training snapshot.
rows[].metrics- Provider ad/day metrics as decimal strings (with video plays, 100% plays, average watch time in seconds and unique clicks); null stays unknown. Daily reach and unique clicks are not additive.
rows[].rankings- Meta's rankings of the ad that day: quality, engagementRate, conversionRate (ABOVE_AVERAGE, AVERAGE, BELOW_AVERAGE_35, BELOW_AVERAGE_20, BELOW_AVERAGE_10, UNKNOWN); absent when Meta gave none.
rows[].resultIndicator- Provider result indicator, when reported.
rows[].timezone- Reported account timezone used for the day.
sinceuntil
curl -X POST "$PLUTO_API/creative-memory/performance" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adIds": [
"120288304425086360"
],
"attribution": "7d_click_1d_view",
"since": "2026-09-01",
"until": "2026-09-27"
}'Quote a targeted precision inspection
Creates a five-minute estimate for one explicit question about an already indexed image, or an original video interval of at most 90 seconds. Creative Memory is an Enterprise add-on: visual and native audio/video inspection use 250 credits per started video minute (50 for an image) from the credit pool; word timing uses no credits. Pins the current parent publications, correction head and policy; any change requires a new estimate. Reserves and dispatches nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
interval- Required original-video interval, at most 90 seconds. Images require null or omission and the visual method.
interval.endMsinterval.startMslanguage- Optional ASR language hint. Alignment requires a separately provisioned compatible checkpoint; unsupported fine timing remains unknown.
mediaId- Already indexed source in this workspace.
method- Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of
visual,native_av,word_timing question- Specific source-grounded question; cannot override model, resource or spending limits.
Response
allowed- All requested new work is currently eligible.
correctionHeadId- Pinned authorized correction generation; null when none.
creditscredits.analyses- Analysis units paid in credits, 50 credits each.
credits.credits- The credits they take at most, paid from the organization's pool before the work starts.
expiresAt- Requote after this time.
id- Accept this exact unexpired quote.
images- New basic image/card indexing.
maxVideoSecondsmethod- Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of
visual,native_av,word_timing policyRevision- Pinned model, extraction and precision policy fingerprint.
publicationIds- Current non-precision source publications required by this result.
question- Question bound to the quote.
reason- Why it cannot proceed.
remaining- Included analysis units left before this request (on an Enterprise contract every analysis is paid in credits, so this is 0).
reusedCount- Items whose existing work is reused.
sourceRevision- Pinned immutable source object revision.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
videoMinutes
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/precision/quote" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a4d3400e-2a71-44ce-b4ba-740a3b5d421d" \
-H "Content-Type: application/json" \
-d '{
"interval": {
"endMs": 12000,
"startMs": 12000
},
"language": "en",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"method": "visual",
"question": "Which ad drove the most purchases last week?"
}'Accept a precision estimate
Accepts the exact estimate by the person or agent who received it. The server rechecks the source, parent evidence, corrections, policy, allowance and terms, then reserves the whole request before any work. At most one paid generation runs; failed or uncertain provider usage is not charged. Accepting the same estimate again returns its original request.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
quoteId- Exact approved, unexpired precision quote.
Response
createdAt- Accepted.
error- Actionable failure, if any.
id- Request.
items- Selected media and original-media sections.
items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].mediaId- Media in this workspace.
items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
jobId- Durable job; use get_job or wait_for_job.
kind- Processing requested.One of
index,deep status- Current execution state, independent of published coverage.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
Errors
- 400The request is malformed.
- 401No valid credential.
- 402Insufficient included allowance or explicitly enabled AI budget.
- 403The credential lacks the permission, or belongs to another workspace.
- 409The estimate expired or its source, evidence or terms changed; request a new one.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/precision/requests" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d6b84063-d9ee-44b6-982c-e1d918306491" \
-H "Content-Type: application/json" \
-d '{
"quoteId": "1fe9ff42-6fed-4524-9c1e-63bea317c338"
}'Read a precision result
The request, its pinned dependencies and, when current, the targeted answer with raw and aligned timing kept separate, coverage, limitations and provenance. A result whose source, parent evidence or correction head changed is marked stale and withheld. Unsupported languages keep unknown fine timing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The request's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
correctionHeadId- Pinned authorized correction generation; changed corrections make this result stale.
method- Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of
visual,native_av,word_timing publicationId- Supplemental evidence publication, if completed.
publicationIds- Current non-precision source publications required by this result.
question- Accepted question.
requestrequest.createdAt- Accepted.
request.error- Actionable failure, if any.
request.id- Request.
request.items- Selected media and original-media sections.
request.items[].endMs- Optional exclusive section end in original-media milliseconds.
request.items[].mediaId- Media in this workspace.
request.items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
request.jobId- Durable job; use get_job or wait_for_job.
request.kind- Processing requested.One of
index,deep request.status- Current execution state, independent of published coverage.
request.units- New analysis units: 50 credits each (an image; a started video minute is 5).
resultresult.coverageresult.coverage.asrresult.coverage.asr.configHash- Extraction policy fingerprint.
result.coverage.asr.coverage- Intervals actually examined, in original-source milliseconds.
result.coverage.asr.frameIds- Examined spatial/frame references; images have no invented time interval.
result.coverage.asr.status- Extractor status, independent of interpretation certainty.One of
succeeded,failed,not_applicable,not_requested,unsupported,skipped result.coverage.asr.warnings- Modality limitations.
result.coverage.audioresult.coverage.audio.configHash- Extraction policy fingerprint.
result.coverage.audio.coverage- Intervals actually examined, in original-source milliseconds.
result.coverage.audio.frameIds- Examined spatial/frame references; images have no invented time interval.
result.coverage.audio.status- Extractor status, independent of interpretation certainty.One of
succeeded,failed,not_applicable,not_requested,unsupported,skipped result.coverage.audio.warnings- Modality limitations.
result.coverage.framesresult.coverage.frames.configHash- Extraction policy fingerprint.
result.coverage.frames.coverage- Intervals actually examined, in original-source milliseconds.
result.coverage.frames.frameIds- Examined spatial/frame references; images have no invented time interval.
result.coverage.frames.status- Extractor status, independent of interpretation certainty.One of
succeeded,failed,not_applicable,not_requested,unsupported,skipped result.coverage.frames.warnings- Modality limitations.
result.coverage.ocrresult.coverage.ocr.configHash- Extraction policy fingerprint.
result.coverage.ocr.coverage- Intervals actually examined, in original-source milliseconds.
result.coverage.ocr.frameIds- Examined spatial/frame references; images have no invented time interval.
result.coverage.ocr.status- Extractor status, independent of interpretation certainty.One of
succeeded,failed,not_applicable,not_requested,unsupported,skipped result.coverage.ocr.warnings- Modality limitations.
result.coverage.shotsresult.coverage.shots.configHash- Extraction policy fingerprint.
result.coverage.shots.coverage- Intervals actually examined, in original-source milliseconds.
result.coverage.shots.frameIds- Examined spatial/frame references; images have no invented time interval.
result.coverage.shots.status- Extractor status, independent of interpretation certainty.One of
succeeded,failed,not_applicable,not_requested,unsupported,skipped result.coverage.shots.warnings- Modality limitations.
result.interpretationresult.interpretation.limitationsresult.interpretation.observationsresult.interpretation.observations[].certainty- observed: the cited evidence covers the whole span. inferred: a reasoned reading that stays within the cited evidence.One of
observed,inferred result.interpretation.observations[].claimresult.interpretation.observations[].endMs- Original-media ms of the latest cited evidence; null for a still image. Frames and text samples are points: consecutive samples cover the time between them only as the rules state.
result.interpretation.observations[].evidenceIds- Supplied evidence IDs that support this claim over its whole span.
result.interpretation.observations[].kind- One of
hook,demonstration,offer,objection,claim,proof,call_to_action,visual,narrative,audio result.interpretation.observations[].startMs- Original-media ms of the earliest cited evidence; null for a still image.
result.interpretation.summary- What the supplied selection shows and says. Never empty.
result.interpretation.summaryEvidenceIds- Supplied evidence IDs supporting the summary. At least one.
result.method- Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of
visual,native_av,word_timing result.observations- Native observations; empty for other methods.
result.observations[].certainty- Provider uncertainty, not verified fact.One of
tentative,supported result.observations[].claim- Source-grounded native inspection claim.
result.observations[].endMs- Estimated original-source end.
result.observations[].modality- Claimed sensory evidence.One of
audio,visual,audio_visual result.observations[].sourceRefs- Verified delivered-clip references.
result.observations[].startMs- Estimated original-source start.
result.provenanceresult.provenance.clipSourceId- Citation for the delivered clip.
result.provenance.deliveryresult.provenance.delivery.assetRef- Original source media.
result.provenance.delivery.audioChannels- Delivered audio channel count.
result.provenance.delivery.audioClipRangeMsresult.provenance.delivery.audioSampleRate- Delivered audio sample rate.
result.provenance.delivery.byteSize- Delivered clip bytes.
result.provenance.delivery.clipVideoPtsMs- Delivered clip frame timestamps.
result.provenance.delivery.contentSha256- Original source hash.
result.provenance.delivery.durationMs- Delivered clip duration.
result.provenance.delivery.height- Delivered video height.
result.provenance.delivery.maxFps- Clip frame-rate cap; actual decoded timestamps are retained.
result.provenance.delivery.mimeType- Delivered clip media type.
result.provenance.delivery.pipelineRevision- Pinned ML extraction revision.
result.provenance.delivery.policy- Clip construction policy.
result.provenance.delivery.requestedIntervalresult.provenance.delivery.schemaVersion- Clip transport contract version.
result.provenance.delivery.sha256- Delivered clip hash.
result.provenance.delivery.sourceAudioChannels- Source audio channel count.
result.provenance.delivery.sourceAudioCoverage- Actual audio coverage; gaps remain explicit.
result.provenance.delivery.sourceAudioRangeMsresult.provenance.delivery.sourceContainerStartMs- Source container start timestamp; not silently treated as zero.
result.provenance.delivery.sourceDurationMs- Original source duration.
result.provenance.delivery.sourceOffsetMs- Original-source offset added to clip-relative timestamps.
result.provenance.delivery.sourceRevision- Immutable source object revision.
result.provenance.delivery.sourceVideoPtsMs- Corresponding source frame timestamps.
result.provenance.delivery.videoClipRangeMsresult.provenance.delivery.warnings- Clip limitations.
result.provenance.delivery.width- Delivered video width.
result.provenance.inspectionIsNotExhaustiveCoverage- True: no claim that every event was examined.
result.provenance.processing- Provider processing mode.
result.provenance.requestedFps- Requested provider video sampling rate; does not certify coverage.
result.provenance.requestedResolution- Requested provider media resolution.One of
LOW,MEDIUM,HIGH result.provenance.sourceFingerprint- Original source fingerprint.
result.provenance.timebase- Converted original source clock.One of
original_source_ms result.provenance.timingMethod- Native model boundaries remain estimates.One of
model_estimate_not_forced_alignment result.publicationIds- Current non-precision source publications required by this result.
result.question- Explicit question answered.
result.sourceRevision- Pinned immutable source revision.
result.status- Result coverage, separate from request execution.One of
ready,partial result.timing- Raw transcript timing and separately recorded alignment.
result.timing[].alignmentresult.timing[].alignment.frameResolutionMs- Model emission spacing, not guaranteed boundary accuracy.
result.timing[].alignment.language- ASR language used to select a reviewed compatible aligner.
result.timing[].alignment.method- Bounded local CTC alignment; does not verify transcript correctness.One of
local_ctc_forced_alignment_v1 result.timing[].alignment.normalization- Explicit transcript-to-vocabulary normalization policy.
result.timing[].alignment.status- Alignment execution and supported-token coverage.One of
succeeded,partial,unsupported,failed result.timing[].alignment.warnings- Alignment limitations and failures.
result.timing[].alignment.words- Words retain their raw text; unsupported or unreliable timing remains null.
result.timing[].endMs- Raw original-source segment end.
result.timing[].id- Original ASR source reference.
result.timing[].language- Reported ASR language; unknown stays null.
result.timing[].rawTimingMethod- Raw ASR timing provenance.
result.timing[].rawWords- Original ASR word estimates, preserved separately from alignment.
result.timing[].rawWords[].endMs- Raw estimated original-source end.
result.timing[].rawWords[].p- ASR token score; not forced alignment.
result.timing[].rawWords[].startMs- Raw estimated original-source start.
result.timing[].rawWords[].w- Raw ASR token.
result.timing[].startMs- Raw original-source segment start.
result.timing[].text- Unmodified transcript segment.
result.warnings- Unknowns and limitations.
sourceRevision- Accepted immutable source revision.
stale- True when source or parent evidence changed; stale results are withheld from this response and ordinary evidence readers.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/precision/requests/d2cf1df9-efd7-4c87-bd42-e589aaca3089" \
-H "Authorization: Bearer $PLUTO_KEY"Cancel a precision request
Stops unfinished work and releases the unused reservation; a late provider receipt cannot publish. Works while the organization is read-only. Retrying does not refund or charge twice.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The request's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- Accepted.
error- Actionable failure, if any.
id- Request.
items- Selected media and original-media sections.
items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].mediaId- Media in this workspace.
items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
jobId- Durable job; use get_job or wait_for_job.
kind- Processing requested.One of
index,deep status- Current execution state, independent of published coverage.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/precision/requests/d2cf1df9-efd7-4c87-bd42-e589aaca3089/cancel" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: cab66c61-59bd-4088-9576-c9cbb20af782"Quote indexing or credits
Quote Creative Memory search indexing or credits.
Creates an expiring quote for selected media and optional original-media sections: reused work (free), the analysis units and credits it takes (250 per started video minute, 50 per image, from the credit pool; indexing uses none) and whether it's allowed. Enterprise only. Does not reserve or dispatch processing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
items- 1–100 new or previously read media/sections; reused stages use no credits or allowance.
items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].mediaId- Media in this workspace.
items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
kind- index: search indexing (speech and on-screen text, no credits); deep: read the files with Creative Memory (Enterprise), 250 credits per started video minute and 50 per image.One of
index,deep
Response
allowed- All requested new work is currently eligible.
creditscredits.analyses- Analysis units paid in credits, 50 credits each.
credits.credits- The credits they take at most, paid from the organization's pool before the work starts.
expiresAt- Requote after this time.
id- Accept this exact unexpired quote.
images- New basic image/card indexing.
maxVideoSecondsreason- Why it cannot proceed.
remaining- Included analysis units left before this request (on an Enterprise contract every analysis is paid in credits, so this is 0).
reusedCount- Items whose existing work is reused.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
videoMinutes
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/quote" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9855f104-e71f-4e71-87f0-5fc51edd80f0" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"endMs": 12000,
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"startMs": 12000
}
],
"kind": "index"
}'List Creative Memory requests
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Previous nextAfter UUID. |
limit | string | Optional | Page size, default 50. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].createdAt- Accepted.
items[].error- Actionable failure, if any.
items[].id- Request.
items[].items- Selected media and original-media sections.
items[].items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].items[].mediaId- Media in this workspace.
items[].items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
items[].jobId- Durable job; use get_job or wait_for_job.
items[].kind- Processing requested.One of
index,deep items[].status- Current execution state, independent of published coverage.
items[].units- New analysis units: 50 credits each (an image; a started video minute is 5).
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/creative-memory/requests" \
-H "Authorization: Bearer $PLUTO_KEY"Accept a Creative Memory quote
Accept the exact approved quoteId. The server revalidates its media, pipeline, terms and credits and atomically reserves the entire request before dispatch. Reuse the Idempotency-Key on retry. New work requires write permission.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
quoteId- Approved, unexpired quote.
Response
createdAt- Accepted.
error- Actionable failure, if any.
id- Request.
items- Selected media and original-media sections.
items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].mediaId- Media in this workspace.
items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
jobId- Durable job; use get_job or wait_for_job.
kind- Processing requested.One of
index,deep status- Current execution state, independent of published coverage.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
Errors
- 400The request is malformed.
- 401No valid credential.
- 402Not enough credits left, or Creative Memory isn't on the plan (Enterprise only).
- 403The credential lacks the permission, or belongs to another workspace.
- 409The quote is stale, expired or changed; request a fresh quote.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/requests" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1ea9268f-959e-4a47-aec4-a295273e5afe" \
-H "Content-Type: application/json" \
-d '{
"quoteId": "1fe9ff42-6fed-4524-9c1e-63bea317c338"
}'Cancel unfinished Creative Memory work
Cancels pending work and releases unused reservations; successfully published stages remain available. Retrying does not refund or charge twice.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The request's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- Accepted.
error- Actionable failure, if any.
id- Request.
items- Selected media and original-media sections.
items[].endMs- Optional exclusive section end in original-media milliseconds.
items[].mediaId- Media in this workspace.
items[].startMs- Optional inclusive section start in original-media milliseconds; give endMs too.
jobId- Durable job; use get_job or wait_for_job.
kind- Processing requested.One of
index,deep status- Current execution state, independent of published coverage.
units- New analysis units: 50 credits each (an image; a started video minute is 5).
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/requests/d2cf1df9-efd7-4c87-bd42-e589aaca3089/cancel" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 42d64224-15d1-4dd8-876f-c84abe45d96f"Search creative evidence
Read published evidence and matching source moments. Reports indexed coverage and retrieval mode. This read starts no new processing and uses no credits; absent evidence is not proof of absence.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Optional | Verbatim query. |
tags | string | Optional | Tag (workflow label) IDs, comma-separated, up to 50: only media used by an ad that isn't archived and has any of them, as in GET /media. Coverage then counts that media only; the cursor keeps the filter. |
after | string | Optional | Previous nextAfter cursor. |
limit | string | Optional | Bounded page size. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
coverage- How many of the files in scope Creative Memory has read. Left out when it couldn't be counted in time; the results are complete without it.
coverage.indexed- Files in scope Creative Memory has read: their evidence is searched.
coverage.total- Ready images and videos in scope, read or not. A file Creative Memory hasn't read is found by its name only; which files it reads on its own is the workspace's
analyzeAutomatically(get_context). incomplete- What this answer left out because it would have taken too long: meaning (text matches only), text (meaning matches only), evidence (results without their matches) or ranking (the files whose names match, one page, no next page). Left out when nothing was; a slow search answers this way instead of failing.
items- This result page.
items[].kind- Media kind.
items[].matches- Matching cited evidence/moments.
items[].matches[].endMs- Original-media end.
items[].matches[].id- Source reference.
items[].matches[].origin- Omitted for recorded model evidence. authorized_correction: a reviewed human correction, an attributed assertion rather than verified truth. revalidation_required: an observation that disagrees with an active correction; it cannot prove a condition.One of
authorized_correction,revalidation_required items[].matches[].source- Evidence modality/source.
items[].matches[].startMs- Original-media start.
items[].matches[].text- Observed evidence.
items[].mediaId- Matching media.
items[].name- Media name.
items[].status- In-depth readiness.
items[].summary- Published interpretation.
mode- Retrieval mode; partial availability is explicit.
nameswhen the search couldn't finish in time and lists the files whose names match. nextAfter- Next page cursor.
resultLimit- Maximum results retained for this search snapshot.
semantic- Meaning-based matching: used, not requested (browsing), off for quoted phrases, or unavailable (text matching only).One of
used,not_requested,literal,unavailable truncated- More candidates exist than this bounded ranked result set. Narrow the query; this is not an exhaustive count.
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-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503
search_busy: search couldn't answer just now (the workspace is running as many searches as it may at once, or a search ran past its time limit). Nothing changed: waitRetry-Afterseconds and ask again.
curl "$PLUTO_API/creative-memory/search" \
-H "Authorization: Bearer $PLUTO_KEY"Get the Creative Memory allowance
Creative Memory for the organization, an Enterprise add-on: whether it's available (and unavailableCode when not), the analysis units used and held this month (50 credits each: 250 credits per started video minute, 50 per image, from the credit pool) and search indexing, which uses no credits. Months are UTC calendar months.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
available- Whether new processing is available.
deepdeep.limitdeep.remainingdeep.reserveddeep.usedimagesimages.limitimages.remainingimages.reservedimages.usedmaxDeepVideoSecondsperiodEnd- Trial expiry or monthly renewal.
periodKind- One trial window or a UTC calendar month.One of
trial,monthly periodStart- Allowance window starts.
unavailableCode- Why it's unavailable: enterprise_only (the trial, Pro or Business: Creative Memory is an Enterprise add-on), not_in_contract (an Enterprise contract without it), no_plan, not_launched.One of
enterprise_only,not_in_contract,no_plan,not_launched unavailableReason- Missing processing availability or agreed terms.
videoMinutesvideoMinutes.limitvideoMinutes.remainingvideoMinutes.reservedvideoMinutes.used
curl "$PLUTO_API/creative-memory/usage" \
-H "Authorization: Bearer $PLUTO_KEY"