API reference

Creative Memory

Search your media and ads by what's in them, and the indexing and credits behind it.

POST/creative-memory/ad-search

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

afterstring
The previous page's nextAfter; send the same q, filters and example.
exampleobject
example.evidenceIdstring (uuid)
Optional: one indexed observation of that file to match instead of the whole file.
example.mediaIdstring (uuid)Required
An indexed media file whose look to match.
filtersobject
filters.adAccountIdstring
A Meta ad account, act_ followed by digits (act_123456789). Limits results to observed Meta ads.
filters.maxDurationMsinteger
Only ads with a video at most this long.
filters.mediaKindstring
Only ads with media of this type.One of image, video
filters.minDurationMsinteger
Only ads with a video at least this long.
filters.subjectKindstring
ad: current Pluto drafts. meta_ad: ads observed at Meta.One of ad, meta_ad
filters.tagsarray of strings (uuid)
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.
limitinteger
Ads per page, default 10 (up to 100); page on with after.
qstring
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.

Response200 OK

coverageobjectRequired
coverage.indexedintegerRequired
Searchable ads in scope.
coverage.partialbooleanRequired
Some eligible ads are not searchable yet; absence from results is not absence.
coverage.pendingintegerRequired
Ads in scope still being prepared for search.
coverage.totalintegerRequired
Eligible ads in scope (media type and length filters excluded).
itemsarray of objectsRequired
This page of ads, best match first.
items[].contextobjectRequired
items[].context.assetsCompletebooleanRequired
Whether the complete media composition is known.
items[].context.copyobjectRequired
Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
items[].context.copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
items[].context.fingerprintstringRequired
Version of this exact composition and source media.
items[].context.limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
items[].context.mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
items[].context.namestringRequired
Creative name.
items[].context.observedAtstring (date-time)Required
When this composition was observed.
items[].context.sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
items[].context.subjectobjectRequired
items[].context.subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
items[].context.subject.mediaIdstring (uuid)
Media in this workspace.
items[].context.subject.adIdstring
Meta ad ID.
items[].context.subject.adAccountIdstring
Optional Meta ad account ID.
items[].creativeRevisionIdstring (uuid)Required
The ad's current contextual revision (copy plus media identities).
items[].matchesarray of objectsRequired
Up to three matching copy fields or media observations.
items[].matches[].endMsinteger or nullRequired
End within the original media.
items[].matches[].fieldstring or nullRequired
Copy field, e.g. copy.primaryText; null for media evidence.
items[].matches[].idstring (uuid)Required
Copy field or evidence ID.
items[].matches[].mediaIdstring (uuid) or nullRequired
The media file this evidence is from.
items[].matches[].provenanceobjectRequired
Where the text comes from, including correction status.
items[].matches[].sourcestringRequired
copy for advertiser-supplied text; otherwise the media observation's source.
items[].matches[].startMsinteger or nullRequired
Start within the original media.
items[].matches[].textstringRequired
Recorded text, at most 4,000 characters.
items[].mediaEvidencestringRequired
What Creative Memory has read of the ad's known media: complete, partial, or none (copy only).One of complete, partial, none
limitationsarray of stringsRequired
What this result set does not cover.
modestringRequired
How results were retrieved.One of text, hybrid, example
nextAfterstring or nullRequired
Cursor for the next page; results stay pinned for two minutes.
resultLimitintegerRequired
Most results one search keeps.
semanticstringRequired
Meaning-based matching: used, not requested (browsing), off for quoted phrases, or unavailable (text matching only).One of used, not_requested, literal, unavailable
truncatedbooleanRequired
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-After seconds. 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"
  }'
GET/creative-memory/addable

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.

Permission: read

Parameters

NameTypeRequiredDescription
mediaIdsquerystringOptionalMedia IDs, comma-separated, 1 to 100.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

allowedbooleanRequired
Whether the caller may add files to Creative Memory now.
itemsarray of objectsRequired
One per distinct file asked about.
items[].mediaIdstring (uuid)Required
The file.
items[].requestIdstring (uuid) or nullRequired
The request reading it, while running.
items[].requestedBystring or nullRequired
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 of person, api_key, agent, system
items[].statestringRequired
Whether it can be added, and if not why.One of addable, analyzed, running, waiting, unsupported

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/addable" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/compare

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

subjectsarray of objectsRequired
Two to eight distinct creatives, in comparison order.
subjects[].kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
subjects[].mediaIdstring (uuid)
Media in this workspace.
subjects[].adIdstring
Meta ad ID.
subjects[].adAccountIdstring
Optional Meta ad account ID.

Response200 OK

differencesarray of objectsRequired
Recorded copy and media differences; missing information cannot prove equality.
differences[].fieldstringRequired
Copy or media field that differs.
differences[].valuesarray of anyRequired
One value per compared creative.
limitationsarray of stringsRequired
Coverage and interpretation limits; this read makes no causal or historical performance claim.
lineageobjectRequired
lineage.familiesarray of objectsRequired
Current family claims that include at least one compared revision.
lineage.families[].actorKindstringRequired
Declarer category.One of person, api_key, agent, system
lineage.families[].basisstringRequired
How the declarer documented the claim.One of creator_declaration, workflow_record, similarity
lineage.families[].limitationsarray of stringsRequired
The claim's recorded interpretation limits.
lineage.families[].membersarray of objectsRequired
All 2–32 recorded member revisions.
lineage.families[].members[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
lineage.families[].members[].fingerprintstringRequired
Exact composition fingerprint the claim was recorded against.
lineage.families[].members[].subjectobjectRequired
lineage.families[].members[].variantIndexinteger or nullRequired
Position in variants when this exact revision is compared; null when it is not.
lineage.families[].namestringRequired
Family name.
lineage.families[].recordIdstring (uuid)Required
Current immutable family record; read it for full sources.
lineage.families[].recordedAtstring (date-time)Required
Server recording time.
lineage.families[].relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
lineage.families[].statusstringRequired
Recorded claim status. Similarity-based claims are never confirmed.One of candidate, confirmed, rejected
lineage.families[].supersedesIdstring (uuid) or nullRequired
Earlier record this claim amended.
lineage.limitationsarray of stringsRequired
Recorded claims are attributed declarations; similarity and shared media never establish lineage.
lineage.relationsarray of objectsRequired
Current variant claims that name at least one compared revision.
lineage.relations[].actorKindstringRequired
Declarer category.One of person, api_key, agent, system
lineage.relations[].basisstringRequired
How the declarer documented the claim.One of creator_declaration, workflow_record, similarity
lineage.relations[].changedComponentsarray of stringsRequired
Declared changed components; unlisted components are not proven unchanged.
lineage.relations[].childobjectRequired
lineage.relations[].child.creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
lineage.relations[].child.fingerprintstringRequired
Exact composition fingerprint the claim was recorded against.
lineage.relations[].child.subjectobjectRequired
lineage.relations[].child.variantIndexinteger or nullRequired
Position in variants when this exact revision is compared; null when it is not.
lineage.relations[].familyIdstring (uuid) or nullRequired
Exact family record named by the claim.
lineage.relations[].limitationsarray of stringsRequired
The claim's recorded interpretation limits.
lineage.relations[].parentobjectRequired
lineage.relations[].parent.creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
lineage.relations[].parent.fingerprintstringRequired
Exact composition fingerprint the claim was recorded against.
lineage.relations[].parent.subjectobjectRequired
lineage.relations[].parent.variantIndexinteger or nullRequired
Position in variants when this exact revision is compared; null when it is not.
lineage.relations[].recordIdstring (uuid)Required
Current immutable relationship record; read it for full sources.
lineage.relations[].recordedAtstring (date-time)Required
Server recording time.
lineage.relations[].relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
lineage.relations[].statusstringRequired
Recorded claim status. Similarity-based claims are never confirmed.One of candidate, confirmed, rejected
lineage.relations[].supersedesIdstring (uuid) or nullRequired
Earlier record this claim amended.
lineage.truncatedbooleanRequired
More than 100 claims matched; this is not the complete family graph.
mediaarray of objectsRequired
Deduplicated available media evidence.
media[].coverageobjectRequired
media[].coverage.descriptionstringRequired
What was and was not examined.
media[].coverage.statusstringRequired
Readiness/coverage status.
media[].evidencearray of objectsRequired
At most 64 source-linked observations for each media item.
media[].evidence[].endMsinteger or nullRequired
Original-media end.
media[].evidence[].idstringRequired
Source reference.
media[].evidence[].originstring
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[].sourcestringRequired
Evidence modality/source.
media[].evidence[].startMsinteger or nullRequired
Original-media start.
media[].evidence[].textstringRequired
Observed evidence.
media[].evidenceTruncatedbooleanRequired
Additional recorded evidence was omitted from this bounded comparison.
media[].mediaIdstring (uuid)Required
Shared source media appears once.
media[].summarystring or nullRequired
Published interpretation, if available.
variantsarray of objectsRequired
Creative compositions in requested order.
variants[].assetsCompletebooleanRequired
Whether the complete media composition is known.
variants[].copyobjectRequired
Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
variants[].copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
variants[].fingerprintstringRequired
Version of this exact composition and source media.
variants[].limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
variants[].mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
variants[].namestringRequired
Creative name.
variants[].observedAtstring (date-time)Required
When this composition was observed.
variants[].sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
variants[].subjectobjectRequired
variants[].subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
variants[].subject.mediaIdstring (uuid)
Media in this workspace.
variants[].subject.adIdstring
Meta ad ID.
variants[].subject.adAccountIdstring
Optional Meta ad account ID.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
      }
    ]
  }'
POST/creative-memory/context

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
mediaIdstring (uuid)
Media in this workspace.
adIdstring
Meta ad ID.
adAccountIdstring
Optional Meta ad account ID.

Response200 OK

assetsCompletebooleanRequired
Whether the complete media composition is known.
copyobjectRequired
Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
fingerprintstringRequired
Version of this exact composition and source media.
limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
namestringRequired
Creative name.
observedAtstring (date-time)Required
When this composition was observed.
sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
subjectobjectRequired
subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
subject.mediaIdstring (uuid)
Media in this workspace.
subject.adIdstring
Meta ad ID.
subject.adAccountIdstring
Optional Meta ad account ID.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/context" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "media",
    "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701"
  }'
GET/creative-memory/corrections

List evidence corrections

Immutable correction and release revisions, newest first, including those for earlier source versions.

Permission: read

Parameters

NameTypeRequiredDescription
mediaIdquerystringOptionalOptional media filter.
afterquerystringOptionalPrevious nextAfter ID.
limitquerystringOptional1–100, default 30.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actorIdstring (uuid)Required
Recorded actor.
items[].actorKindstringRequired
Actual actor origin.One of person, api_key, agent, system
items[].assetIdstring (uuid)Required
Exact verified asset.
items[].beforeobject or nullRequired
items[].before.endMsinteger or nullRequired
Original-media end.
items[].before.idstring (uuid)Required
Raw evidence or immutable correction ID.
items[].before.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
items[].before.publicationIdstring (uuid)Required
Effective publication source.
items[].before.sourcestringRequired
Original evidence modality.
items[].before.sourceRefstringRequired
Original or conflict-qualified source reference.
items[].before.startMsinteger or nullRequired
Original-media start.
items[].before.textstringRequired
Recorded text.
items[].createdAtstring (date-time)Required
Server publication time.
items[].idstring (uuid)Required
Immutable correction revision.
items[].limitationsarray of stringsRequired
Evidence is attributed, lexical-ready, and not independently verified.
items[].mediaIdstring (uuid)Required
Media.
items[].operationstringRequired
Explicit correction or release.One of edit, release
items[].patchIdsarray of strings (uuid)Required
Effective patch set after this command.
items[].previousIdstring (uuid) or nullRequired
Previous overlay head.
items[].provenanceobjectRequired
items[].provenance.auditIdsarray of strings (uuid)
items[].provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
items[].provenance.notestringRequired
Document how this relationship or allocation is known.
items[].provenance.referencesarray of objects
items[].provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
items[].provenance.references[].titlestringRequired
Source document title.
items[].provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
items[].publicationIdsarray of strings (uuid)Required
Accepted publication set.
items[].rationalestringRequired
Recorded rationale.
items[].rebasesCorrectionIdstring (uuid) or nullRequired
Historical edit explicitly rebased.
items[].replacementobject or nullRequired
items[].replacement.endMsinteger or nullRequired
Original video end, null for images.
items[].replacement.startMsinteger or nullRequired
Original video start, null for images.
items[].replacement.textstringRequired
items[].schemaVersionstringRequired
Correction contract version.
items[].sourceFingerprintstringRequired
Source version.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/corrections" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/corrections

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

evidenceIdstring (uuid)Required
Exact effective evidence reviewed.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationalestringRequired
Why the source supports this correction.
rebasesCorrectionIdstring (uuid) or null
Optional historical correction being explicitly rebased onto the newly reviewed evidence.
replacementobject or nullRequired
An explicit replacement; null explicitly retracts this evidence.
replacement.endMsinteger or nullRequired
Original video end, null for images.
replacement.startMsinteger or nullRequired
Original video start, null for images.
replacement.textstringRequired
snapshotobjectRequired
snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdsarray of strings (uuid)Required
snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
snapshot.mediaIdstring (uuid)Required
Exact source media.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actual actor origin.One of person, api_key, agent, system
assetIdstring (uuid)Required
Exact verified asset.
beforeobject or nullRequired
before.endMsinteger or nullRequired
Original-media end.
before.idstring (uuid)Required
Raw evidence or immutable correction ID.
before.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationIdstring (uuid)Required
Effective publication source.
before.sourcestringRequired
Original evidence modality.
before.sourceRefstringRequired
Original or conflict-qualified source reference.
before.startMsinteger or nullRequired
Original-media start.
before.textstringRequired
Recorded text.
createdAtstring (date-time)Required
Server publication time.
idstring (uuid)Required
Immutable correction revision.
limitationsarray of stringsRequired
Evidence is attributed, lexical-ready, and not independently verified.
mediaIdstring (uuid)Required
Media.
operationstringRequired
Explicit correction or release.One of edit, release
patchIdsarray of strings (uuid)Required
Effective patch set after this command.
previousIdstring (uuid) or nullRequired
Previous overlay head.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIdsarray of strings (uuid)Required
Accepted publication set.
rationalestringRequired
Recorded rationale.
rebasesCorrectionIdstring (uuid) or nullRequired
Historical edit explicitly rebased.
replacementobject or nullRequired
replacement.endMsinteger or nullRequired
Original video end, null for images.
replacement.startMsinteger or nullRequired
Original video start, null for images.
replacement.textstringRequired
schemaVersionstringRequired
Correction contract version.
sourceFingerprintstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    }
  }'
POST/creative-memory/corrections/release

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationalestringRequired
Why all active corrections for this exact source are being released.
snapshotobjectRequired
snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdsarray of strings (uuid)Required
snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
snapshot.mediaIdstring (uuid)Required
Exact source media.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actual actor origin.One of person, api_key, agent, system
assetIdstring (uuid)Required
Exact verified asset.
beforeobject or nullRequired
before.endMsinteger or nullRequired
Original-media end.
before.idstring (uuid)Required
Raw evidence or immutable correction ID.
before.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationIdstring (uuid)Required
Effective publication source.
before.sourcestringRequired
Original evidence modality.
before.sourceRefstringRequired
Original or conflict-qualified source reference.
before.startMsinteger or nullRequired
Original-media start.
before.textstringRequired
Recorded text.
createdAtstring (date-time)Required
Server publication time.
idstring (uuid)Required
Immutable correction revision.
limitationsarray of stringsRequired
Evidence is attributed, lexical-ready, and not independently verified.
mediaIdstring (uuid)Required
Media.
operationstringRequired
Explicit correction or release.One of edit, release
patchIdsarray of strings (uuid)Required
Effective patch set after this command.
previousIdstring (uuid) or nullRequired
Previous overlay head.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIdsarray of strings (uuid)Required
Accepted publication set.
rationalestringRequired
Recorded rationale.
rebasesCorrectionIdstring (uuid) or nullRequired
Historical edit explicitly rebased.
replacementobject or nullRequired
replacement.endMsinteger or nullRequired
Original video end, null for images.
replacement.startMsinteger or nullRequired
Original video start, null for images.
replacement.textstringRequired
schemaVersionstringRequired
Correction contract version.
sourceFingerprintstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    }
  }'
GET/creative-memory/corrections/{id}

Read an evidence correction

One immutable correction or release revision with the reviewed before value, replacement, rationale and actor provenance.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe correction's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actual actor origin.One of person, api_key, agent, system
assetIdstring (uuid)Required
Exact verified asset.
beforeobject or nullRequired
before.endMsinteger or nullRequired
Original-media end.
before.idstring (uuid)Required
Raw evidence or immutable correction ID.
before.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
before.publicationIdstring (uuid)Required
Effective publication source.
before.sourcestringRequired
Original evidence modality.
before.sourceRefstringRequired
Original or conflict-qualified source reference.
before.startMsinteger or nullRequired
Original-media start.
before.textstringRequired
Recorded text.
createdAtstring (date-time)Required
Server publication time.
idstring (uuid)Required
Immutable correction revision.
limitationsarray of stringsRequired
Evidence is attributed, lexical-ready, and not independently verified.
mediaIdstring (uuid)Required
Media.
operationstringRequired
Explicit correction or release.One of edit, release
patchIdsarray of strings (uuid)Required
Effective patch set after this command.
previousIdstring (uuid) or nullRequired
Previous overlay head.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
publicationIdsarray of strings (uuid)Required
Accepted publication set.
rationalestringRequired
Recorded rationale.
rebasesCorrectionIdstring (uuid) or nullRequired
Historical edit explicitly rebased.
replacementobject or nullRequired
replacement.endMsinteger or nullRequired
Original video end, null for images.
replacement.startMsinteger or nullRequired
Original video start, null for images.
replacement.textstringRequired
schemaVersionstringRequired
Correction contract version.
sourceFingerprintstringRequired
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-After seconds. 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"
POST/creative-memory/evaluate

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

conditionobjectRequired
condition.caseSensitiveboolean
Defaults to false.
condition.opstringRequired
Bounded recorded-evidence temporal predicate.One of repetitions
condition.textstring
Literal phrase in recorded evidence; 1-500 characters. This does not assert physical absence.
condition.kindstring
Interpretation feature. Missing interpretations remain unknown.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.conditionobject
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.endMsinteger
Exclusive end greater than start. Prior coverage is required.
condition.startMsinteger
Inclusive original-source start of first-occurrence window within evaluated scope.
condition.conditionsarray of objects
One or more child conditions.
condition.eventobject
condition.event.caseSensitiveboolean
Defaults to false.
condition.event.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.event.textstring
condition.event.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.toleranceMsinteger
Default 0. Expands accepted comparison thresholds only; not calibrated model accuracy.
condition.anchorobject
condition.anchor.caseSensitiveboolean
Defaults to false.
condition.anchor.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.anchor.textstring
condition.anchor.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.maxDelayMsinteger
Inclusive maximum delay, at least minDelayMs.
condition.minDelayMsinteger
Inclusive minimum start-of-event minus end-of-anchor delay; default 0.
condition.anchorEdgestring
Anchor endpoint; event uses its start.One of start, end
condition.endOffsetMsinteger
Signed original-time offset from the selected anchor edge.
condition.startOffsetMsinteger
Signed original-time offset from the selected anchor edge.
condition.leftobject
condition.left.caseSensitiveboolean
Defaults to false.
condition.left.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.left.textstring
condition.left.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.minOverlapMsinteger
Positive supported overlap; touching endpoints and broad intersecting envelopes are insufficient.
condition.rightobject
condition.right.caseSensitiveboolean
Defaults to false.
condition.right.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.right.textstring
condition.right.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.maxMsinteger
Inclusive maximum occurrence duration, at least minMs. A transcript container is not a phrase duration.
condition.minMsinteger
Inclusive minimum occurrence duration.
condition.maxCountinteger or null
Optional inclusive maximum. Missing coverage cannot establish an upper count. Sampled visual persistence is not repetitions.
condition.minCountinteger
mediaIdstring (uuid)Required
Media in this workspace.
scopeobject
scope.endMsintegerRequired
Exclusive original-media end.
scope.startMsintegerRequired
Inclusive original-media start.

Response200 OK

conditionobjectRequired
condition.caseSensitiveboolean
Defaults to false.
condition.opstringRequired
Bounded recorded-evidence temporal predicate.One of repetitions
condition.textstring
Literal phrase in recorded evidence; 1-500 characters. This does not assert physical absence.
condition.kindstring
Interpretation feature. Missing interpretations remain unknown.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.conditionobject
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.endMsinteger
Exclusive end greater than start. Prior coverage is required.
condition.startMsinteger
Inclusive original-source start of first-occurrence window within evaluated scope.
condition.conditionsarray of objects
One or more child conditions.
condition.eventobject
condition.event.caseSensitiveboolean
Defaults to false.
condition.event.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.event.textstring
condition.event.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.toleranceMsinteger
Default 0. Expands accepted comparison thresholds only; not calibrated model accuracy.
condition.anchorobject
condition.anchor.caseSensitiveboolean
Defaults to false.
condition.anchor.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.anchor.textstring
condition.anchor.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.maxDelayMsinteger
Inclusive maximum delay, at least minDelayMs.
condition.minDelayMsinteger
Inclusive minimum start-of-event minus end-of-anchor delay; default 0.
condition.anchorEdgestring
Anchor endpoint; event uses its start.One of start, end
condition.endOffsetMsinteger
Signed original-time offset from the selected anchor edge.
condition.startOffsetMsinteger
Signed original-time offset from the selected anchor edge.
condition.leftobject
condition.left.caseSensitiveboolean
Defaults to false.
condition.left.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.left.textstring
condition.left.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.minOverlapMsinteger
Positive supported overlap; touching endpoints and broad intersecting envelopes are insufficient.
condition.rightobject
condition.right.caseSensitiveboolean
Defaults to false.
condition.right.opstringRequired
Recorded interpretation, not a detector of absence.One of feature
condition.right.textstring
condition.right.kindstring
Feature type.One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
condition.maxMsinteger
Inclusive maximum occurrence duration, at least minMs. A transcript container is not a phrase duration.
condition.minMsinteger
Inclusive minimum occurrence duration.
condition.maxCountinteger or null
Optional inclusive maximum. Missing coverage cannot establish an upper count. Sampled visual persistence is not repetitions.
condition.minCountinteger
correctionHeadIdstring (uuid) or nullRequired
Current authorized correction generation included in the evaluation fingerprint.
coveragearray of stringsRequired
Missing, partial or truncated evidence remains explicit.
evaluationHashstringRequired
Condition, source and active evidence generation fingerprint.
evidencearray of objectsRequired
Cited supporting observations.
evidence[].endMsinteger or nullRequired
Original-media end.
evidence[].idstringRequired
Source reference.
evidence[].originstring
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[].sourcestringRequired
Evidence modality/source.
evidence[].startMsinteger or nullRequired
Original-media start.
evidence[].textstringRequired
Observed evidence.
predicateHashstringRequired
Canonical condition and scope fingerprint.
scopeobject or nullRequired
scope.endMsintegerRequired
Exclusive original-source end.
scope.startMsintegerRequired
Inclusive original-source start.
semanticsstringRequired
Results describe recorded evidence, not certified physical truth.One of recorded_evidence
sourceRevisionstringRequired
Exact current source fingerprint.
valuestringRequired
Three-valued result over recorded evidence, not physical ground truth.One of true, false, unknown
versionstringRequired
Predicate semantics version.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
    }
  }'
GET/creative-memory/experiments

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.

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalPrevious nextAfter experiment ID.
limitquerystringOptional1–100, default 40.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].createdAtstring (date-time)Required
First registration.
items[].currentVersionintegerRequired
Latest immutable design version.
items[].firstAssessedAtstring or nullRequired
Earliest Pluto outcome-read attempt; retained even if reading failed.
items[].idstring (uuid)Required
Experiment ID.
items[].revisionobjectRequired
items[].revision.actorIdstring (uuid)Required
Declaring actor.
items[].revision.actorKindstringRequired
Actor category.One of person, api_key, agent, system
items[].revision.amendmentReasonstring or nullRequired
Why an immutable revision was appended.
items[].revision.designobjectRequired
items[].revision.design.allocationobjectRequired
items[].revision.design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
items[].revision.design.creativeChangestringRequired
The planned intervention and what differs.
items[].revision.design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
items[].revision.design.groupsarray of objectsRequired
items[].revision.design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
items[].revision.design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
items[].revision.design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
items[].revision.design.namestringRequired
Experiment name.
items[].revision.design.primaryMetricobjectRequired
items[].revision.design.stoppingRuleobjectRequired
items[].revision.design.windowobjectRequired
items[].revision.experimentIdstring (uuid)Required
Experiment ID.
items[].revision.fingerprintstringRequired
Versioned immutable design and source fingerprint.
items[].revision.limitationsarray of stringsRequired
Design and causal-inference limitations.
items[].revision.preregisteredbooleanRequired
This revision was registered before its window and any declared or recorded assessment; no causal proof.
items[].revision.priorResultsSeenbooleanRequired
Registrant's current attestation.
items[].revision.registeredAtstring (date-time)Required
Server registration time.
items[].revision.registrationTimingstringRequired
Server-calculated temporal qualification.One of prospective, historical_window, prior_results_declared, amendment_after_assessment, amendment_after_start
items[].revision.schemaVersionstringRequired
Design contract version.
items[].revision.sourcesarray of objectsRequired
Source-backed comparison groups.
items[].revision.sources[].creativesarray of objectsRequired
Exact server-resolved revisions.
items[].revision.sources[].groupKeystringRequired
Registered comparison group.
items[].revision.versionintegerRequired
Immutable design version.
items[].statusstringRequired
Current administrative status; not an inference result.One of registered, running, completed, cancelled
items[].updatedAtstring (date-time)Required
Latest administrative change.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/experiments" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/experiments

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

designobjectRequired
design.allocationobjectRequired
design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
design.allocation.provenanceobjectRequired
design.allocation.provenance.auditIdsarray of strings (uuid)
design.allocation.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
design.allocation.provenance.notestringRequired
Document how this relationship or allocation is known.
design.allocation.provenance.referencesarray of objects
design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
design.creativeChangestringRequired
The planned intervention and what differs.
design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
design.groupsarray of objectsRequired
design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
design.groups[].creativesarray of objectsRequired
design.groups[].creatives[].expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
design.groups[].creatives[].subjectobjectRequired
design.groups[].keystringRequired
design.groups[].namestringRequired
Comparison group name.
design.groups[].rolestringRequired
Exactly one control.One of control, treatment
design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
design.namestringRequired
Experiment name.
design.primaryMetricobjectRequired
design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
design.stoppingRule.kindstringRequired
One of sequential
design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
design.stoppingRule.maximumLooksinteger
design.stoppingRule.schedulestring
Prespecified analysis schedule.
design.windowobjectRequired
design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
design.window.sincestring (date)Required
Inclusive first account-local day.
design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
priorResultsSeenbooleanRequired
Whether anyone registering this revision has already assessed relevant results outside this recording. Must be truthful.

Response200 OK

createdAtstring (date-time)Required
First registration.
currentVersionintegerRequired
Latest immutable design version.
firstAssessedAtstring or nullRequired
Earliest Pluto outcome-read attempt; retained even if reading failed.
idstring (uuid)Required
Experiment ID.
revisionobjectRequired
revision.actorIdstring (uuid)Required
Declaring actor.
revision.actorKindstringRequired
Actor category.One of person, api_key, agent, system
revision.amendmentReasonstring or nullRequired
Why an immutable revision was appended.
revision.designobjectRequired
revision.design.allocationobjectRequired
revision.design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
revision.design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
revision.design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
revision.design.allocation.provenanceobjectRequired
revision.design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
revision.design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
revision.design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
revision.design.creativeChangestringRequired
The planned intervention and what differs.
revision.design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
revision.design.groupsarray of objectsRequired
revision.design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesarray of objectsRequired
revision.design.groups[].keystringRequired
revision.design.groups[].namestringRequired
Comparison group name.
revision.design.groups[].rolestringRequired
Exactly one control.One of control, treatment
revision.design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
revision.design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
revision.design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
revision.design.namestringRequired
Experiment name.
revision.design.primaryMetricobjectRequired
revision.design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
revision.design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
revision.design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
revision.design.stoppingRule.kindstringRequired
One of sequential
revision.design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksinteger
revision.design.stoppingRule.schedulestring
Prespecified analysis schedule.
revision.design.windowobjectRequired
revision.design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
revision.design.window.sincestring (date)Required
Inclusive first account-local day.
revision.design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
revision.design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
revision.experimentIdstring (uuid)Required
Experiment ID.
revision.fingerprintstringRequired
Versioned immutable design and source fingerprint.
revision.limitationsarray of stringsRequired
Design and causal-inference limitations.
revision.preregisteredbooleanRequired
This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeenbooleanRequired
Registrant's current attestation.
revision.registeredAtstring (date-time)Required
Server registration time.
revision.registrationTimingstringRequired
Server-calculated temporal qualification.One of prospective, historical_window, prior_results_declared, amendment_after_assessment, amendment_after_start
revision.schemaVersionstringRequired
Design contract version.
revision.sourcesarray of objectsRequired
Source-backed comparison groups.
revision.sources[].creativesarray of objectsRequired
Exact server-resolved revisions.
revision.sources[].creatives[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextobjectRequired
revision.sources[].creatives[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryobject or nullRequired
revision.sources[].groupKeystringRequired
Registered comparison group.
revision.versionintegerRequired
Immutable design version.
statusstringRequired
Current administrative status; not an inference result.One of registered, running, completed, cancelled
updatedAtstring (date-time)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
GET/creative-memory/experiments/{id}

Read a creative experiment

Reads the experiment with the requested immutable design revision, its source snapshots, registration timing and limitations.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe experiment's ID.
versionquerystringOptionalImmutable design version; default is the current one.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

createdAtstring (date-time)Required
First registration.
currentVersionintegerRequired
Latest immutable design version.
firstAssessedAtstring or nullRequired
Earliest Pluto outcome-read attempt; retained even if reading failed.
idstring (uuid)Required
Experiment ID.
revisionobjectRequired
revision.actorIdstring (uuid)Required
Declaring actor.
revision.actorKindstringRequired
Actor category.One of person, api_key, agent, system
revision.amendmentReasonstring or nullRequired
Why an immutable revision was appended.
revision.designobjectRequired
revision.design.allocationobjectRequired
revision.design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
revision.design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
revision.design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
revision.design.allocation.provenanceobjectRequired
revision.design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
revision.design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
revision.design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
revision.design.creativeChangestringRequired
The planned intervention and what differs.
revision.design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
revision.design.groupsarray of objectsRequired
revision.design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesarray of objectsRequired
revision.design.groups[].keystringRequired
revision.design.groups[].namestringRequired
Comparison group name.
revision.design.groups[].rolestringRequired
Exactly one control.One of control, treatment
revision.design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
revision.design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
revision.design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
revision.design.namestringRequired
Experiment name.
revision.design.primaryMetricobjectRequired
revision.design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
revision.design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
revision.design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
revision.design.stoppingRule.kindstringRequired
One of sequential
revision.design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksinteger
revision.design.stoppingRule.schedulestring
Prespecified analysis schedule.
revision.design.windowobjectRequired
revision.design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
revision.design.window.sincestring (date)Required
Inclusive first account-local day.
revision.design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
revision.design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
revision.experimentIdstring (uuid)Required
Experiment ID.
revision.fingerprintstringRequired
Versioned immutable design and source fingerprint.
revision.limitationsarray of stringsRequired
Design and causal-inference limitations.
revision.preregisteredbooleanRequired
This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeenbooleanRequired
Registrant's current attestation.
revision.registeredAtstring (date-time)Required
Server registration time.
revision.registrationTimingstringRequired
Server-calculated temporal qualification.One of prospective, historical_window, prior_results_declared, amendment_after_assessment, amendment_after_start
revision.schemaVersionstringRequired
Design contract version.
revision.sourcesarray of objectsRequired
Source-backed comparison groups.
revision.sources[].creativesarray of objectsRequired
Exact server-resolved revisions.
revision.sources[].creatives[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextobjectRequired
revision.sources[].creatives[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryobject or nullRequired
revision.sources[].groupKeystringRequired
Registered comparison group.
revision.versionintegerRequired
Immutable design version.
statusstringRequired
Current administrative status; not an inference result.One of registered, running, completed, cancelled
updatedAtstring (date-time)Required
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-After seconds. 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"
POST/creative-memory/experiments/{id}/amendments

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe experiment's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

designobjectRequired
design.allocationobjectRequired
design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
design.allocation.provenanceobjectRequired
design.allocation.provenance.auditIdsarray of strings (uuid)
design.allocation.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
design.allocation.provenance.notestringRequired
Document how this relationship or allocation is known.
design.allocation.provenance.referencesarray of objects
design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
design.creativeChangestringRequired
The planned intervention and what differs.
design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
design.groupsarray of objectsRequired
design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
design.groups[].creativesarray of objectsRequired
design.groups[].creatives[].expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
design.groups[].creatives[].subjectobjectRequired
design.groups[].keystringRequired
design.groups[].namestringRequired
Comparison group name.
design.groups[].rolestringRequired
Exactly one control.One of control, treatment
design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
design.namestringRequired
Experiment name.
design.primaryMetricobjectRequired
design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
design.stoppingRule.kindstringRequired
One of sequential
design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
design.stoppingRule.maximumLooksinteger
design.stoppingRule.schedulestring
Prespecified analysis schedule.
design.windowobjectRequired
design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
design.window.sincestring (date)Required
Inclusive first account-local day.
design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
priorResultsSeenbooleanRequired
Whether relevant results have already been assessed.
reasonstringRequired
Why the registered design is amended.

Response200 OK

createdAtstring (date-time)Required
First registration.
currentVersionintegerRequired
Latest immutable design version.
firstAssessedAtstring or nullRequired
Earliest Pluto outcome-read attempt; retained even if reading failed.
idstring (uuid)Required
Experiment ID.
revisionobjectRequired
revision.actorIdstring (uuid)Required
Declaring actor.
revision.actorKindstringRequired
Actor category.One of person, api_key, agent, system
revision.amendmentReasonstring or nullRequired
Why an immutable revision was appended.
revision.designobjectRequired
revision.design.allocationobjectRequired
revision.design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
revision.design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
revision.design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
revision.design.allocation.provenanceobjectRequired
revision.design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
revision.design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
revision.design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
revision.design.creativeChangestringRequired
The planned intervention and what differs.
revision.design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
revision.design.groupsarray of objectsRequired
revision.design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesarray of objectsRequired
revision.design.groups[].keystringRequired
revision.design.groups[].namestringRequired
Comparison group name.
revision.design.groups[].rolestringRequired
Exactly one control.One of control, treatment
revision.design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
revision.design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
revision.design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
revision.design.namestringRequired
Experiment name.
revision.design.primaryMetricobjectRequired
revision.design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
revision.design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
revision.design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
revision.design.stoppingRule.kindstringRequired
One of sequential
revision.design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksinteger
revision.design.stoppingRule.schedulestring
Prespecified analysis schedule.
revision.design.windowobjectRequired
revision.design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
revision.design.window.sincestring (date)Required
Inclusive first account-local day.
revision.design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
revision.design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
revision.experimentIdstring (uuid)Required
Experiment ID.
revision.fingerprintstringRequired
Versioned immutable design and source fingerprint.
revision.limitationsarray of stringsRequired
Design and causal-inference limitations.
revision.preregisteredbooleanRequired
This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeenbooleanRequired
Registrant's current attestation.
revision.registeredAtstring (date-time)Required
Server registration time.
revision.registrationTimingstringRequired
Server-calculated temporal qualification.One of prospective, historical_window, prior_results_declared, amendment_after_assessment, amendment_after_start
revision.schemaVersionstringRequired
Design contract version.
revision.sourcesarray of objectsRequired
Source-backed comparison groups.
revision.sources[].creativesarray of objectsRequired
Exact server-resolved revisions.
revision.sources[].creatives[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextobjectRequired
revision.sources[].creatives[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryobject or nullRequired
revision.sources[].groupKeystringRequired
Registered comparison group.
revision.versionintegerRequired
Immutable design version.
statusstringRequired
Current administrative status; not an inference result.One of registered, running, completed, cancelled
updatedAtstring (date-time)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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."
  }'
GET/creative-memory/experiments/{id}/outcomes

List observed experiment outcomes

Immutable outcome snapshots, each pinned to the design version it assessed. Every outcome is descriptive only.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe experiment's ID.
afterquerystringOptionalPrevious nextAfter outcome ID.
limitquerystringOptional1–50, default 20.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actorIdstring (uuid)Required
Assessing actor.
items[].actorKindstringRequired
Actor category.One of person, api_key, agent, system
items[].designFingerprintstringRequired
Exact assessed source and design identity.
items[].designVersionintegerRequired
Exact assessed design version.
items[].experimentIdstring (uuid)Required
Experiment.
items[].factsobjectRequired
items[].facts.attributionstringRequired
Requested provider attribution window.
items[].facts.limitationsarray of stringsRequired
Coverage, observation, delivery and causal limitations.
items[].facts.maxBracketHoursintegerRequired
Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
items[].facts.missingAdIdsarray of stringsRequired
Missing days and metrics are not zero-filled.
items[].facts.requestedAdIdsarray of stringsRequired
Requested ads.
items[].facts.retrievedAtstring (date-time)Required
When Pluto assembled this read.
items[].facts.rowsarray of objectsRequired
Original ad/day facts; outcomes are never duplicated or allocated to each asset.
items[].facts.rows[].actionValuesmap of string
The value of each action type, in the account currency.
items[].facts.rows[].actionsmap of string
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[].adAccountIdstringRequired
Source Meta ad account.
items[].facts.rows[].adIdstringRequired
Source Meta ad.
items[].facts.rows[].adsetIdstringRequired
Reported ad set.
items[].facts.rows[].attributionstringRequired
Exact provider attribution window.
items[].facts.rows[].campaignIdstringRequired
Reported campaign.
items[].facts.rows[].compositionobjectRequired
items[].facts.rows[].currencystringRequired
Reported account currency.
items[].facts.rows[].datestring (date)Required
items[].facts.rows[].denominatorsmap of stringRequired
Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
items[].facts.rows[].fetchedAtstring (date-time)Required
When this latest stored provider fact was fetched; not a point-in-time training snapshot.
items[].facts.rows[].metricsmap of stringRequired
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[].rankingsobject
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[].resultIndicatorstring or nullRequired
Provider result indicator, when reported.
items[].facts.rows[].timezonestringRequired
Reported account timezone used for the day.
items[].facts.sincestring (date)Required
items[].facts.untilstring (date)Required
items[].factsFingerprintstringRequired
Hash of the exact preserved facts.
items[].groupAdIdsmap of array of stringsRequired
items[].idstring (uuid)Required
Immutable observed outcome ID.
items[].inferencestringRequired
One of descriptive_only
items[].limitationsarray of stringsRequired
Sample, allocation, stopping and composition caveats.
items[].notestringRequired
Recorded capture reason.
items[].observedAtstring (date-time)Required
Snapshot capture time.
items[].untilstring (date)Required
Captured end day.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/experiments/e045e351-ebc2-46b5-a3d8-36ebdfa0cf26/outcomes" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/experiments/{id}/outcomes

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe experiment's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
notestringRequired
Reason for taking this immutable outcome snapshot.
untilstring (date)Required
Completed account-local end day inside the registered window.

Response200 OK

actorIdstring (uuid)Required
Assessing actor.
actorKindstringRequired
Actor category.One of person, api_key, agent, system
designFingerprintstringRequired
Exact assessed source and design identity.
designVersionintegerRequired
Exact assessed design version.
experimentIdstring (uuid)Required
Experiment.
factsobjectRequired
facts.attributionstringRequired
Requested provider attribution window.
facts.limitationsarray of stringsRequired
Coverage, observation, delivery and causal limitations.
facts.maxBracketHoursintegerRequired
Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
facts.missingAdIdsarray of stringsRequired
Missing days and metrics are not zero-filled.
facts.requestedAdIdsarray of stringsRequired
Requested ads.
facts.retrievedAtstring (date-time)Required
When Pluto assembled this read.
facts.rowsarray of objectsRequired
Original ad/day facts; outcomes are never duplicated or allocated to each asset.
facts.rows[].actionValuesmap of string
The value of each action type, in the account currency.
facts.rows[].actionsmap of string
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[].adAccountIdstringRequired
Source Meta ad account.
facts.rows[].adIdstringRequired
Source Meta ad.
facts.rows[].adsetIdstringRequired
Reported ad set.
facts.rows[].attributionstringRequired
Exact provider attribution window.
facts.rows[].campaignIdstringRequired
Reported campaign.
facts.rows[].compositionobjectRequired
facts.rows[].composition.assumedContinuitybooleanRequired
True means matching snapshots assume continuity; intermediate changes were not observed.
facts.rows[].composition.creativeIdstring or nullRequired
Only set for an observed stable bracket; not a delivered dynamic asset ID.
facts.rows[].composition.firstObservedAtstring or nullRequired
Earliest supporting observation time.
facts.rows[].composition.lastObservedAtstring or nullRequired
Latest supporting observation time.
facts.rows[].composition.observationCountintegerRequired
Supporting observations.
facts.rows[].composition.reasonstringRequired
Why composition is stable, mixed or unknown.
facts.rows[].composition.statusstringRequired
Matching observed snapshots, unresolved changes or missing coverage.One of observed_stable, mixed, unknown
facts.rows[].composition.validFromstring or nullRequired
Inferred start of a fully bracketed account-local day; not an exact provider change time.
facts.rows[].composition.validUntilstring or nullRequired
Inferred exclusive end of that bracketed day.
facts.rows[].currencystringRequired
Reported account currency.
facts.rows[].datestring (date)Required
facts.rows[].denominatorsmap of stringRequired
Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
facts.rows[].fetchedAtstring (date-time)Required
When this latest stored provider fact was fetched; not a point-in-time training snapshot.
facts.rows[].metricsmap of stringRequired
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[].rankingsobject
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[].resultIndicatorstring or nullRequired
Provider result indicator, when reported.
facts.rows[].timezonestringRequired
Reported account timezone used for the day.
facts.sincestring (date)Required
facts.untilstring (date)Required
factsFingerprintstringRequired
Hash of the exact preserved facts.
groupAdIdsmap of array of stringsRequired
idstring (uuid)Required
Immutable observed outcome ID.
inferencestringRequired
One of descriptive_only
limitationsarray of stringsRequired
Sample, allocation, stopping and composition caveats.
notestringRequired
Recorded capture reason.
observedAtstring (date-time)Required
Snapshot capture time.
untilstring (date)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/creative-memory/experiments/{id}/status

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe experiment's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
reasonstringRequired
Reason for the state transition.
statusstringRequired
Allowed transitions: registered to running/cancelled; running to completed/cancelled.One of registered, running, completed, cancelled

Response200 OK

createdAtstring (date-time)Required
First registration.
currentVersionintegerRequired
Latest immutable design version.
firstAssessedAtstring or nullRequired
Earliest Pluto outcome-read attempt; retained even if reading failed.
idstring (uuid)Required
Experiment ID.
revisionobjectRequired
revision.actorIdstring (uuid)Required
Declaring actor.
revision.actorKindstringRequired
Actor category.One of person, api_key, agent, system
revision.amendmentReasonstring or nullRequired
Why an immutable revision was appended.
revision.designobjectRequired
revision.design.allocationobjectRequired
revision.design.allocation.interferencePolicystringRequired
How repeated exposure, spillover and overlap are handled.
revision.design.allocation.methodstringRequired
Declared design; actual execution is not independently verified.One of randomized, quasi_experimental, observational
revision.design.allocation.procedurestringRequired
Document assignment mechanism and planned allocation.
revision.design.allocation.provenanceobjectRequired
revision.design.allocation.unitstringRequired
Experimental unit, not the reported aggregation level.One of person, household, geography, campaign, ad_set, ad, time_block
revision.design.allocation.unitDefinitionstringRequired
Define the eligible experimental unit and population.
revision.design.counterargumentsarray of stringsRequired
Alternative explanations that may falsify the hypothesis.
revision.design.creativeChangestringRequired
The planned intervention and what differs.
revision.design.creativeChangeIsolatedbooleanRequired
A declaration of isolation, not a verified claim.
revision.design.groupsarray of objectsRequired
revision.design.groups[].allocationSharestringRequired
Positive share below one; all group shares sum exactly to one.
revision.design.groups[].creativesarray of objectsRequired
revision.design.groups[].keystringRequired
revision.design.groups[].namestringRequired
Comparison group name.
revision.design.groups[].rolestringRequired
Exactly one control.One of control, treatment
revision.design.heldConstantarray of stringsRequired
Conditions intended to remain equal.
revision.design.hypothesisstringRequired
Falsifiable hypothesis recorded before results.
revision.design.knownConfoundersarray of stringsRequired
Known differences that limit attribution.
revision.design.namestringRequired
Experiment name.
revision.design.primaryMetricobjectRequired
revision.design.primaryMetric.attributionstringRequired
Exact provider attribution window.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
revision.design.primaryMetric.definitionstringRequired
Metric interpretation and aggregation, including unit and missing-value policy.
revision.design.primaryMetric.denominatorstring or null
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.directionstringRequired
Prespecified desired direction.One of increase, decrease
revision.design.primaryMetric.numeratorstringRequired
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.stoppingRuleobjectRequired
revision.design.stoppingRule.kindstringRequired
One of sequential
revision.design.stoppingRule.minimumUnitsPerGroupstringRequired
Positive whole-number experimental units required per group; not inferred from impressions.
revision.design.stoppingRule.decisionRulestring
Prespecified sequential stopping rule and uncertainty method.
revision.design.stoppingRule.maximumLooksinteger
revision.design.stoppingRule.schedulestring
Prespecified analysis schedule.
revision.design.windowobjectRequired
revision.design.window.currencystringRequired
Accepted ISO currency matching all enrolled accounts.
revision.design.window.sincestring (date)Required
Inclusive first account-local day.
revision.design.window.timezonestringRequired
IANA timezone matching all enrolled accounts.
revision.design.window.untilstring (date)Required
Inclusive last day; at most 31 days.
revision.experimentIdstring (uuid)Required
Experiment ID.
revision.fingerprintstringRequired
Versioned immutable design and source fingerprint.
revision.limitationsarray of stringsRequired
Design and causal-inference limitations.
revision.preregisteredbooleanRequired
This revision was registered before its window and any declared or recorded assessment; no causal proof.
revision.priorResultsSeenbooleanRequired
Registrant's current attestation.
revision.registeredAtstring (date-time)Required
Server registration time.
revision.registrationTimingstringRequired
Server-calculated temporal qualification.One of prospective, historical_window, prior_results_declared, amendment_after_assessment, amendment_after_start
revision.schemaVersionstringRequired
Design contract version.
revision.sourcesarray of objectsRequired
Source-backed comparison groups.
revision.sources[].creativesarray of objectsRequired
Exact server-resolved revisions.
revision.sources[].creatives[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
revision.sources[].creatives[].contextobjectRequired
revision.sources[].creatives[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
revision.sources[].creatives[].deliveryobject or nullRequired
revision.sources[].groupKeystringRequired
Registered comparison group.
revision.versionintegerRequired
Immutable design version.
statusstringRequired
Current administrative status; not an inference result.One of registered, running, completed, cancelled
updatedAtstring (date-time)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
GET/creative-memory/imports

List library imports

Explicit historical basic-index imports, newest first, with progress joined from each accepted child request.

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalThe previous page's nextAfter.
limitquerystringOptionalPage size, 1 to 100 (default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
items[].createdAtstring (date-time)Required
Creation time.
items[].cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
items[].idstring (uuid)Required
Durable parent ID.
items[].jobIdstring (uuid)Required
Current parent job in Activity.
items[].progressobjectRequired
items[].progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
items[].reasonstring or nullRequired
Pause or cancellation explanation.
items[].scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
items[].scopeobjectRequired
items[].scope.kindstringRequired
Only these media IDs.One of selected
items[].scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
items[].statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
items[].updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
items[].watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
items[].watermarkIdstring (uuid)Required
Inclusive media-ID boundary.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/imports" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/imports

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
    }
  }'
GET/creative-memory/imports/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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-After seconds. 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"
POST/creative-memory/imports/{id}/cancel

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: a9eb8796-9f77-45f8-b780-e29cdf4b4833"
GET/creative-memory/imports/{id}/items

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
afterquerystringOptionalThe previous page's nextAfter.
limitquerystringOptionalPage size, 1 to 100 (default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].attemptintegerRequired
Zero-based attempt for this source revision.
items[].idstring (uuid)Required
Revision attempt ID.
items[].mediaIdstring (uuid)Required
Original media ID, retained even if deleted.
items[].reasonstring or nullRequired
Skip or child failure explanation.
items[].requestIdstring (uuid) or nullRequired
Ordinary Creative Memory child; null before acceptance or if its record was removed.
items[].sourceRevisionstringRequired
Immutable source fingerprint; unavailable observations have their own fingerprint.
items[].statusstringRequired
Actual child status when accepted; no inferred success.One of pending, queued, running, ready, partial, failed, cancelled, skipped, unavailable
items[].supersededbooleanRequired
An explicit retry superseded this attempt; its child receipt remains intact.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/items" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/imports/{id}/items/{itemId}/retry

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
itemIdpathstringRequiredThe item's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
POST/creative-memory/imports/{id}/pause

Pause a library import

Stops new submissions at the current checkpoint; accepted children continue. Works while the organization is read-only.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/pause" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 8d39501f-9778-4bc6-aa3d-9abef29f388e"
POST/creative-memory/imports/{id}/resume

Resume a library import

Continues a paused import from its checkpoint, including one paused because the included allowance ran out.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe import's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

changesPendingintegerRequired
Coalesced source-change notifications still awaiting discovery.
createdAtstring (date-time)Required
Creation time.
cursorIdstring (uuid) or nullRequired
Last enumerated media ID.
idstring (uuid)Required
Durable parent ID.
jobIdstring (uuid)Required
Current parent job in Activity.
progressobjectRequired
progress.cancelledintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.discoveredintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.failedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.partialintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.pendingintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.queuedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.readyintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.runningintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.skippedintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
progress.unavailableintegerRequired
Revision attempts in this state; superseded retries are kept in item history.
reasonstring or nullRequired
Pause or cancellation explanation.
scanCompletebooleanRequired
Whether initial keyset enumeration finished; accepted child jobs may still be running.
scopeobjectRequired
scope.kindstringRequired
Only these media IDs.One of selected
scope.mediaIdsarray of strings (uuid)
Explicit fixed media selection.
statusstringRequired
Parent submission state. Cancellation stops future submissions; existing children keep their actual state.One of running, paused, completed, cancelled
updatedAtstring (date-time)Required
Latest parent checkpoint or control time.
watermarkAtstring (date-time)Required
Immutable scope cutoff; new uploads require their own indexing or a later import.
watermarkIdstring (uuid)Required
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0/resume" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: db641cc6-b9cd-4661-8896-4ca1a5d16701"
GET/creative-memory/labels

List learning labels

Explicit content-accuracy, query-relevance and user-utility annotations, newest first. They are unverified judgments, separate from corrections and ad outcomes.

Permission: read

Parameters

NameTypeRequiredDescription
mediaIdquerystringOptionalOptional media filter.
afterquerystringOptionalPrevious nextAfter ID.
limitquerystringOptional1–100, default 40.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actorIdstring (uuid)Required
Recorded actor.
items[].actorKindstringRequired
Actual actor, never assumed to be human.One of person, api_key, agent, system
items[].assetIdstring (uuid)Required
Exact verified source.
items[].createdAtstring (date-time)Required
Server recording time.
items[].evidenceobject or nullRequired
items[].evidence.endMsinteger or nullRequired
Original-media end.
items[].evidence.idstring (uuid)Required
Raw evidence or immutable correction ID.
items[].evidence.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
items[].evidence.publicationIdstring (uuid)Required
Effective publication source.
items[].evidence.sourcestringRequired
Original evidence modality.
items[].evidence.sourceRefstringRequired
Original or conflict-qualified source reference.
items[].evidence.startMsinteger or nullRequired
Original-media start.
items[].evidence.textstringRequired
Recorded text.
items[].idstring (uuid)Required
Immutable annotation.
items[].inputobjectRequired
items[].input.annotationobjectRequired
items[].input.annotation.evidenceIdstring (uuid) or null
Optional particular evidence.
items[].input.annotation.kindstringRequired
One of user_utility
items[].input.annotation.verdictstringRequired
Explicit utility judgment; no automatic label from a click.One of useful, not_useful, uncertain
items[].input.annotation.querystring
Explicit query whose relevance is judged.
items[].input.provenanceobjectRequired
items[].input.provenance.auditIdsarray of strings (uuid)
items[].input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
items[].input.provenance.notestringRequired
Document how this relationship or allocation is known.
items[].input.provenance.referencesarray of objects
items[].input.rationalestringRequired
Reason for the explicit annotation.
items[].input.snapshotobjectRequired
items[].input.snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
items[].input.snapshot.expectedPublicationIdsarray of strings (uuid)Required
items[].input.snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
items[].input.snapshot.mediaIdstring (uuid)Required
Exact source media.
items[].input.supersedesIdstring (uuid) or null
Latest label being corrected; history remains immutable.
items[].limitationsarray of stringsRequired
Label stream and truth constraints.
items[].originstringRequired
One of explicit_annotation
items[].schemaVersionstringRequired
Label contract version.
items[].verifierStatusstringRequired
One of unverified
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/labels" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/labels

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

annotationobjectRequired
annotation.evidenceIdstring (uuid) or null
Optional particular evidence.
annotation.kindstringRequired
One of user_utility
annotation.verdictstringRequired
Explicit utility judgment; no automatic label from a click.One of useful, not_useful, uncertain
annotation.querystring
Explicit query whose relevance is judged.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
rationalestringRequired
Reason for the explicit annotation.
snapshotobjectRequired
snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdsarray of strings (uuid)Required
snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
snapshot.mediaIdstring (uuid)Required
Exact source media.
supersedesIdstring (uuid) or null
Latest label being corrected; history remains immutable.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actual actor, never assumed to be human.One of person, api_key, agent, system
assetIdstring (uuid)Required
Exact verified source.
createdAtstring (date-time)Required
Server recording time.
evidenceobject or nullRequired
evidence.endMsinteger or nullRequired
Original-media end.
evidence.idstring (uuid)Required
Raw evidence or immutable correction ID.
evidence.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence.publicationIdstring (uuid)Required
Effective publication source.
evidence.sourcestringRequired
Original evidence modality.
evidence.sourceRefstringRequired
Original or conflict-qualified source reference.
evidence.startMsinteger or nullRequired
Original-media start.
evidence.textstringRequired
Recorded text.
idstring (uuid)Required
Immutable annotation.
inputobjectRequired
input.annotationobjectRequired
input.annotation.evidenceIdstring (uuid) or null
Optional particular evidence.
input.annotation.kindstringRequired
One of user_utility
input.annotation.verdictstringRequired
Explicit utility judgment; no automatic label from a click.One of useful, not_useful, uncertain
input.annotation.querystring
Explicit query whose relevance is judged.
input.provenanceobjectRequired
input.provenance.auditIdsarray of strings (uuid)
input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
input.provenance.notestringRequired
Document how this relationship or allocation is known.
input.provenance.referencesarray of objects
input.provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
input.provenance.references[].titlestringRequired
Source document title.
input.provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.rationalestringRequired
Reason for the explicit annotation.
input.snapshotobjectRequired
input.snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
input.snapshot.expectedPublicationIdsarray of strings (uuid)Required
input.snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
input.snapshot.mediaIdstring (uuid)Required
Exact source media.
input.supersedesIdstring (uuid) or null
Latest label being corrected; history remains immutable.
limitationsarray of stringsRequired
Label stream and truth constraints.
originstringRequired
One of explicit_annotation
schemaVersionstringRequired
Label contract version.
verifierStatusstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
GET/creative-memory/labels/{id}

Read a learning label

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe label's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actual actor, never assumed to be human.One of person, api_key, agent, system
assetIdstring (uuid)Required
Exact verified source.
createdAtstring (date-time)Required
Server recording time.
evidenceobject or nullRequired
evidence.endMsinteger or nullRequired
Original-media end.
evidence.idstring (uuid)Required
Raw evidence or immutable correction ID.
evidence.provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence.publicationIdstring (uuid)Required
Effective publication source.
evidence.sourcestringRequired
Original evidence modality.
evidence.sourceRefstringRequired
Original or conflict-qualified source reference.
evidence.startMsinteger or nullRequired
Original-media start.
evidence.textstringRequired
Recorded text.
idstring (uuid)Required
Immutable annotation.
inputobjectRequired
input.annotationobjectRequired
input.annotation.evidenceIdstring (uuid) or null
Optional particular evidence.
input.annotation.kindstringRequired
One of user_utility
input.annotation.verdictstringRequired
Explicit utility judgment; no automatic label from a click.One of useful, not_useful, uncertain
input.annotation.querystring
Explicit query whose relevance is judged.
input.provenanceobjectRequired
input.provenance.auditIdsarray of strings (uuid)
input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
input.provenance.notestringRequired
Document how this relationship or allocation is known.
input.provenance.referencesarray of objects
input.provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
input.provenance.references[].titlestringRequired
Source document title.
input.provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.rationalestringRequired
Reason for the explicit annotation.
input.snapshotobjectRequired
input.snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
input.snapshot.expectedPublicationIdsarray of strings (uuid)Required
input.snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
input.snapshot.mediaIdstring (uuid)Required
Exact source media.
input.supersedesIdstring (uuid) or null
Latest label being corrected; history remains immutable.
limitationsarray of stringsRequired
Label stream and truth constraints.
originstringRequired
One of explicit_annotation
schemaVersionstringRequired
Label contract version.
verifierStatusstringRequired
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-After seconds. 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"
GET/creative-memory/lineage

List recorded creative relationships

Current (not superseded) variant and family claims with their pinned source revisions. Similarity never confirms a relationship.

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalPrevious nextAfter record ID.
limitquerystringOptional1–100, default 40.
fingerprintquerystringOptionalOnly claims naming this exact recorded revision fingerprint.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].actorIdstring (uuid)Required
Recorded actor.
items[].actorKindstringRequired
Actor category.One of person, api_key, agent, system
items[].createdAtstring (date-time)Required
Server recording time.
items[].idstring (uuid)Required
Immutable relationship record.
items[].inputobjectRequired
items[].input.amendmentReasonstring or null
Required when superseding a record.
items[].input.provenanceobjectRequired
items[].input.provenance.auditIdsarray of strings (uuid)
items[].input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
items[].input.provenance.notestringRequired
Document how this relationship or allocation is known.
items[].input.provenance.referencesarray of objects
items[].input.recordobjectRequired
items[].input.record.changedComponentsarray of strings
items[].input.record.childobject
items[].input.record.familyIdstring (uuid) or null
Optional exact recorded family containing both revisions.
items[].input.record.kindstringRequired
One of family
items[].input.record.parentobject
items[].input.record.relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
items[].input.record.descriptionstring
Documented basis for membership.
items[].input.record.membersarray of objects
items[].input.record.namestring
Family name.
items[].input.statusstringRequired
Confirmation requires declared or recorded provenance; never similarity alone.One of candidate, confirmed, rejected
items[].input.supersedesIdstring (uuid) or null
Latest record to amend; historical records remain available.
items[].limitationsarray of stringsRequired
Explicit interpretation limits.
items[].schemaVersionstringRequired
Creative lineage contract version.
items[].sourcesarray of objectsRequired
Exact server-resolved source revisions.
items[].sources[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
items[].sources[].assets[].byteSizeintegerRequired
Verified source byte size.
items[].sources[].assets[].durationMsinteger or nullRequired
Original video duration, null for images.
items[].sources[].assets[].kindstringRequired
Media kind.
items[].sources[].assets[].mediaIdstring (uuid)Required
Pinned source media.
items[].sources[].assets[].sha256stringRequired
Verified original bytes hash.
items[].sources[].assets[].sourceFingerprintstringRequired
Exact asset revision fingerprint.
items[].sources[].contextobjectRequired
items[].sources[].context.assetsCompletebooleanRequired
Whether the complete media composition is known.
items[].sources[].context.copyobjectRequired
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.copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
items[].sources[].context.fingerprintstringRequired
Version of this exact composition and source media.
items[].sources[].context.limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
items[].sources[].context.mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
items[].sources[].context.namestringRequired
Creative name.
items[].sources[].context.observedAtstring (date-time)Required
When this composition was observed.
items[].sources[].context.sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
items[].sources[].context.subjectobjectRequired
items[].sources[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
items[].sources[].deliveryobject or nullRequired
items[].sources[].delivery.adAccountIdstringRequired
Source account.
items[].sources[].delivery.adIdstringRequired
Observed Meta ad ID.
items[].sources[].delivery.creativeIdstring or nullRequired
Observed Meta creative ID, null when unavailable.
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/lineage" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/lineage

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

amendmentReasonstring or null
Required when superseding a record.
provenanceobjectRequired
provenance.auditIdsarray of strings (uuid)
provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
provenance.notestringRequired
Document how this relationship or allocation is known.
provenance.referencesarray of objects
provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
provenance.references[].titlestringRequired
Source document title.
provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
recordobjectRequired
record.changedComponentsarray of strings
record.childobject
record.child.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
record.child.subjectobjectRequired
record.child.subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
record.child.subject.mediaIdstring (uuid)
Media in this workspace.
record.child.subject.adIdstring
Meta ad ID.
record.child.subject.adAccountIdstring
Optional Meta ad account ID.
record.familyIdstring (uuid) or null
Optional exact recorded family containing both revisions.
record.kindstringRequired
One of family
record.parentobject
record.parent.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
record.parent.subjectobjectRequired
record.parent.subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
record.parent.subject.mediaIdstring (uuid)
Media in this workspace.
record.parent.subject.adIdstring
Meta ad ID.
record.parent.subject.adAccountIdstring
Optional Meta ad account ID.
record.relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
record.descriptionstring
Documented basis for membership.
record.membersarray of objects
record.members[].expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
record.members[].subjectobjectRequired
record.members[].subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
record.members[].subject.mediaIdstring (uuid)
Media in this workspace.
record.members[].subject.adIdstring
Meta ad ID.
record.members[].subject.adAccountIdstring
Optional Meta ad account ID.
record.namestring
Family name.
statusstringRequired
Confirmation requires declared or recorded provenance; never similarity alone.One of candidate, confirmed, rejected
supersedesIdstring (uuid) or null
Latest record to amend; historical records remain available.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actor category.One of person, api_key, agent, system
createdAtstring (date-time)Required
Server recording time.
idstring (uuid)Required
Immutable relationship record.
inputobjectRequired
input.amendmentReasonstring or null
Required when superseding a record.
input.provenanceobjectRequired
input.provenance.auditIdsarray of strings (uuid)
input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
input.provenance.notestringRequired
Document how this relationship or allocation is known.
input.provenance.referencesarray of objects
input.provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
input.provenance.references[].titlestringRequired
Source document title.
input.provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.recordobjectRequired
input.record.changedComponentsarray of strings
input.record.childobject
input.record.child.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.child.subjectobjectRequired
input.record.familyIdstring (uuid) or null
Optional exact recorded family containing both revisions.
input.record.kindstringRequired
One of family
input.record.parentobject
input.record.parent.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.parent.subjectobjectRequired
input.record.relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
input.record.descriptionstring
Documented basis for membership.
input.record.membersarray of objects
input.record.members[].expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.members[].subjectobjectRequired
input.record.namestring
Family name.
input.statusstringRequired
Confirmation requires declared or recorded provenance; never similarity alone.One of candidate, confirmed, rejected
input.supersedesIdstring (uuid) or null
Latest record to amend; historical records remain available.
limitationsarray of stringsRequired
Explicit interpretation limits.
schemaVersionstringRequired
Creative lineage contract version.
sourcesarray of objectsRequired
Exact server-resolved source revisions.
sources[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
sources[].assets[].byteSizeintegerRequired
Verified source byte size.
sources[].assets[].durationMsinteger or nullRequired
Original video duration, null for images.
sources[].assets[].kindstringRequired
Media kind.
sources[].assets[].mediaIdstring (uuid)Required
Pinned source media.
sources[].assets[].sha256stringRequired
Verified original bytes hash.
sources[].assets[].sourceFingerprintstringRequired
Exact asset revision fingerprint.
sources[].contextobjectRequired
sources[].context.assetsCompletebooleanRequired
Whether the complete media composition is known.
sources[].context.copyobjectRequired
Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
sources[].context.copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
sources[].context.fingerprintstringRequired
Version of this exact composition and source media.
sources[].context.limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
sources[].context.mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
sources[].context.namestringRequired
Creative name.
sources[].context.observedAtstring (date-time)Required
When this composition was observed.
sources[].context.sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
sources[].context.subjectobjectRequired
sources[].context.subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
sources[].context.subject.mediaIdstring (uuid)
Media in this workspace.
sources[].context.subject.adIdstring
Meta ad ID.
sources[].context.subject.adAccountIdstring
Optional Meta ad account ID.
sources[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
sources[].deliveryobject or nullRequired
sources[].delivery.adAccountIdstringRequired
Source account.
sources[].delivery.adIdstringRequired
Observed Meta ad ID.
sources[].delivery.creativeIdstring or nullRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
GET/creative-memory/lineage/{id}

Read a recorded creative relationship

Reads one immutable claim, current or superseded, with its declarer and pinned source revisions.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe lineage's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actorIdstring (uuid)Required
Recorded actor.
actorKindstringRequired
Actor category.One of person, api_key, agent, system
createdAtstring (date-time)Required
Server recording time.
idstring (uuid)Required
Immutable relationship record.
inputobjectRequired
input.amendmentReasonstring or null
Required when superseding a record.
input.provenanceobjectRequired
input.provenance.auditIdsarray of strings (uuid)
input.provenance.basisstringRequired
Workflow claims require a workspace audit event. Similarity never confirms ancestry.One of creator_declaration, workflow_record, similarity
input.provenance.notestringRequired
Document how this relationship or allocation is known.
input.provenance.referencesarray of objects
input.provenance.references[].observedAtstring (date-time)Required
When the declarer observed this source, no future dates.
input.provenance.references[].titlestringRequired
Source document title.
input.provenance.references[].urlstringRequired
Dated HTTP or HTTPS source; credentials forbidden. Not independently fetched.
input.recordobjectRequired
input.record.changedComponentsarray of strings
input.record.childobject
input.record.child.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.child.subjectobjectRequired
input.record.familyIdstring (uuid) or null
Optional exact recorded family containing both revisions.
input.record.kindstringRequired
One of family
input.record.parentobject
input.record.parent.expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.parent.subjectobjectRequired
input.record.relationshipstringRequired
Declared relationship, not inferred causality.One of derived_from, translation, edit, shared_concept, controlled_variation
input.record.descriptionstring
Documented basis for membership.
input.record.membersarray of objects
input.record.members[].expectedFingerprintstringRequired
Exact current context fingerprint; changes cause a conflict.
input.record.members[].subjectobjectRequired
input.record.namestring
Family name.
input.statusstringRequired
Confirmation requires declared or recorded provenance; never similarity alone.One of candidate, confirmed, rejected
input.supersedesIdstring (uuid) or null
Latest record to amend; historical records remain available.
limitationsarray of stringsRequired
Explicit interpretation limits.
schemaVersionstringRequired
Creative lineage contract version.
sourcesarray of objectsRequired
Exact server-resolved source revisions.
sources[].assetsarray of objectsRequired
Verified source revisions, no bucket keys or signed URLs.
sources[].assets[].byteSizeintegerRequired
Verified source byte size.
sources[].assets[].durationMsinteger or nullRequired
Original video duration, null for images.
sources[].assets[].kindstringRequired
Media kind.
sources[].assets[].mediaIdstring (uuid)Required
Pinned source media.
sources[].assets[].sha256stringRequired
Verified original bytes hash.
sources[].assets[].sourceFingerprintstringRequired
Exact asset revision fingerprint.
sources[].contextobjectRequired
sources[].context.assetsCompletebooleanRequired
Whether the complete media composition is known.
sources[].context.copyobjectRequired
Declared primary text, headlines, descriptions, call to action and destination. Missing fields stay null; copy is not independent verification of its claims.
sources[].context.copyCompletebooleanRequired
Whether all advertiser-supplied copy is represented.
sources[].context.fingerprintstringRequired
Version of this exact composition and source media.
sources[].context.limitationsarray of stringsRequired
Why some composition or evidence remains unknown.
sources[].context.mediaIdsarray of strings (uuid)Required
Media available for evidence lookup.
sources[].context.namestringRequired
Creative name.
sources[].context.observedAtstring (date-time)Required
When this composition was observed.
sources[].context.sourcestringRequired
Draft, media or a recorded published Meta snapshot/readback.
sources[].context.subjectobjectRequired
sources[].context.subject.kindstringRequired
Observed published Meta ad; never substitute its current draft.One of meta_ad
sources[].context.subject.mediaIdstring (uuid)
Media in this workspace.
sources[].context.subject.adIdstring
Meta ad ID.
sources[].context.subject.adAccountIdstring
Optional Meta ad account ID.
sources[].creativeRevisionIdstring (uuid) or nullRequired
Persisted ad composition revision; null for standalone media.
sources[].deliveryobject or nullRequired
sources[].delivery.adAccountIdstringRequired
Source account.
sources[].delivery.adIdstringRequired
Observed Meta ad ID.
sources[].delivery.creativeIdstring or nullRequired
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-After seconds. 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"
GET/creative-memory/media/{id}

Read creative evidence and coverage

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

automaticAnalysisobject or null
automaticAnalysis.renewsAtstring (date-time) or nullRequired
When the included credits reset, with waiting_for_allowance.
automaticAnalysis.statusstringRequired
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
coverageobjectRequired
coverage.descriptionstringRequired
What was and was not examined.
coverage.statusstringRequired
Readiness/coverage status.
evidencearray of objectsRequired
Cited observations, preserving source timestamps.
evidence[].endMsinteger or nullRequired
Original-media end.
evidence[].idstringRequired
Source reference.
evidence[].originstring
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[].sourcestringRequired
Evidence modality/source.
evidence[].startMsinteger or nullRequired
Original-media start.
evidence[].textstringRequired
Observed evidence.
mediaIdstring (uuid)Required
Media.
requestsarray of objectsRequired
Processing requests.
requests[].createdAtstring (date-time)Required
Accepted.
requests[].errorstring or nullRequired
Actionable failure, if any.
requests[].idstring (uuid)Required
Request.
requests[].itemsarray of objectsRequired
Selected media and original-media sections.
requests[].items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
requests[].items[].mediaIdstring (uuid)Required
Media in this workspace.
requests[].items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
requests[].jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
requests[].kindstringRequired
Processing requested.One of index, deep
requests[].statusstringRequired
Current execution state, independent of published coverage.
requests[].unitsintegerRequired
New analysis units: 50 credits each (an image; a started video minute is 5).
statusstringRequired
Available in-depth readiness.
summarystring or nullRequired
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-After seconds. 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"
GET/creative-memory/media/{id}/correction-context

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe media's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

activePatchIdsarray of strings (uuid)Required
Read correction history by these IDs to revise a retracted observation.
assetIdstring (uuid)Required
Verified source revision.
conflictedbooleanRequired
A later raw baseline requires explicit revalidation.
editedbooleanRequired
An active manual overlay exists.
evidencearray of objectsRequired
At most 500 effective source-linked documents.
evidence[].endMsinteger or nullRequired
Original-media end.
evidence[].idstring (uuid)Required
Raw evidence or immutable correction ID.
evidence[].provenanceobjectRequired
Raw or correction provenance. correctionConflict means revalidation is required; authorized_correction is an attributed assertion, never independent verification.
evidence[].publicationIdstring (uuid)Required
Effective publication source.
evidence[].sourcestringRequired
Original evidence modality.
evidence[].sourceRefstringRequired
Original or conflict-qualified source reference.
evidence[].startMsinteger or nullRequired
Original-media start.
evidence[].textstringRequired
Recorded text.
evidenceTruncatedbooleanRequired
More evidence exists beyond this bounded preview.
historicalCorrectionIdsarray of strings (uuid)Required
At most 50 recent historical revisions requiring explicit rebase.
limitationsarray of stringsRequired
Origin and coverage constraints.
snapshotobjectRequired
snapshot.expectedCorrectionIdstring (uuid) or nullRequired
Reviewed manual overlay head, null before the first edit.
snapshot.expectedPublicationIdsarray of strings (uuid)Required
Reviewed active publications; empty while the media has none.
snapshot.expectedSourceFingerprintstringRequired
Reviewed current source fingerprint.
snapshot.mediaIdstring (uuid)Required
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-After seconds. 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"
GET/creative-memory/monitors

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.

Permission: read

Parameters

NameTypeRequiredDescription
loopIdquerystringOptionalOnly coverage runs of this loop.
afterquerystringOptionalThe previous page's nextAfter.
limitquerystringOptionalPage size, 1 to 100 (default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Coverage runs.
items[].actionLimitintegerRequired
Maximum matching subjects passed to ordinary Loop branches.
items[].actionsLimitedintegerRequired
Known matches not offered because the bounded action selection excluded them.
items[].completedAtstring or nullRequired
Coverage completion time, absent for incomplete or canceled evaluation.
items[].configobjectRequired
Pinned scope, condition, predicateVersion, quantifier and actionLimit from the Loop version.
items[].currentSequenceintegerRequired
Current workspace change sequence; newer means coverage may be stale.
items[].enumerationCompletebooleanRequired
All subjects in scope and captured changes were enumerated.
items[].evaluationCompletebooleanRequired
Every enumerated subject reached an explicit result; this does not mean every result is known or every action ran.
items[].freshbooleanRequired
No newer recorded dependency notification exists.
items[].idstring (uuid)Required
Coverage run ID.
items[].loopIdstring (uuid)Required
Owning saved Loop.
items[].loopRunIdstring (uuid)Required
Existing Loop job/run ID.
items[].loopVersionintegerRequired
Immutable approved definition version.
items[].membersAfterstring or nullRequired
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[].runCountsobjectRequired
items[].runCounts.deletedintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.failedintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.knownFalseintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.knownTrueintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.missingintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.pendingintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.totalintegerRequired
Subject count in this state; unknown is never false.
items[].runCounts.unknownintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCountsobjectRequired
items[].scopeCounts.deletedintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.failedintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.knownFalseintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.knownTrueintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.missingintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.pendingintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.totalintegerRequired
Subject count in this state; unknown is never false.
items[].scopeCounts.unknownintegerRequired
Subject count in this state; unknown is never false.
items[].selectedintegerRequired
Subjects offered to normal Loop execution, not completed actions.
items[].statusstringRequired
Owning Loop execution status, including cancelled and failed.
items[].stepIdstringRequired
Saved creative-monitor step.
items[].throughSequenceintegerRequired
Content change sequence incorporated into this run.
items[].watermarkAtstring (date-time)Required
Membership cutoff: only subjects that existed at this time belong to this run; later subjects wait for a later run.
nextAfterstring (uuid) or nullRequired
Next cursor.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/monitors" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/creative-memory/monitors/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe monitor's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actionLimitintegerRequired
Maximum matching subjects passed to ordinary Loop branches.
actionsLimitedintegerRequired
Known matches not offered because the bounded action selection excluded them.
completedAtstring or nullRequired
Coverage completion time, absent for incomplete or canceled evaluation.
configobjectRequired
Pinned scope, condition, predicateVersion, quantifier and actionLimit from the Loop version.
currentSequenceintegerRequired
Current workspace change sequence; newer means coverage may be stale.
enumerationCompletebooleanRequired
All subjects in scope and captured changes were enumerated.
evaluationCompletebooleanRequired
Every enumerated subject reached an explicit result; this does not mean every result is known or every action ran.
freshbooleanRequired
No newer recorded dependency notification exists.
idstring (uuid)Required
Coverage run ID.
loopIdstring (uuid)Required
Owning saved Loop.
loopRunIdstring (uuid)Required
Existing Loop job/run ID.
loopVersionintegerRequired
Immutable approved definition version.
membersAfterstring or nullRequired
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.
runCountsobjectRequired
runCounts.deletedintegerRequired
Subject count in this state; unknown is never false.
runCounts.failedintegerRequired
Subject count in this state; unknown is never false.
runCounts.knownFalseintegerRequired
Subject count in this state; unknown is never false.
runCounts.knownTrueintegerRequired
Subject count in this state; unknown is never false.
runCounts.missingintegerRequired
Subject count in this state; unknown is never false.
runCounts.pendingintegerRequired
Subject count in this state; unknown is never false.
runCounts.totalintegerRequired
Subject count in this state; unknown is never false.
runCounts.unknownintegerRequired
Subject count in this state; unknown is never false.
scopeCountsobjectRequired
scopeCounts.deletedintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.failedintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.knownFalseintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.knownTrueintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.missingintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.pendingintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.totalintegerRequired
Subject count in this state; unknown is never false.
scopeCounts.unknownintegerRequired
Subject count in this state; unknown is never false.
selectedintegerRequired
Subjects offered to normal Loop execution, not completed actions.
statusstringRequired
Owning Loop execution status, including cancelled and failed.
stepIdstringRequired
Saved creative-monitor step.
throughSequenceintegerRequired
Content change sequence incorporated into this run.
watermarkAtstring (date-time)Required
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-After seconds. 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"
GET/creative-memory/monitors/{id}/items

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe monitor's ID.
afterquerystringOptionalThe previous page's nextAfter (a subject ID).
limitquerystringOptionalPage size, 1 to 100 (default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This run's evaluated or pending subjects; older unchanged scope results remain in scopeCounts.
items[].actionOutcomestring or nullRequired
Existing Loop item outcome; null is not success.
items[].changedbooleanRequired
Relevant dependencies changed since the monitor's prior result.
items[].dependencyHashstring or nullRequired
Normalized content, correction and predicate identity; vectors are excluded.
items[].evaluationobject or nullRequired
Recorded-evidence result and limitations.
items[].executionstringRequired
Selection for ordinary Loop execution, independently of predicate truth.One of not_selected, offered, unchanged, limited, no_action
items[].observedAtstring or nullRequired
Last successful evaluation/reuse time.
items[].statestringRequired
Evaluation execution state.One of pending, evaluated, missing, deleted, failed
items[].subjectobjectRequired
Explicit media, draft ad or Meta ad subject.
items[].subjectIdstringRequired
Stable scoped subject ID.
items[].valuestring or nullRequired
Predicate truth; null means still pending.One of true, false, unknown
nextAfterstring or nullRequired
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-After seconds. 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"
POST/creative-memory/performance

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adIdsarray of stringsRequired
Distinct requested ads; outcomes remain at ad/day level.
attributionstringRequired
Exact provider attribution window; no windows are added together.One of 7d_click_1d_view, 7d_click, 1d_click, 1d_view, 28d_click
sincestring (date)Required
Inclusive account-local first date (YYYY-MM-DD).
untilstring (date)Required
Inclusive account-local last date; at most 31 days total.

Response200 OK

attributionstringRequired
Requested provider attribution window.
limitationsarray of stringsRequired
Coverage, observation, delivery and causal limitations.
maxBracketHoursintegerRequired
Maximum allowed gap between supporting observations; a freshness policy, not verified continuity.
missingAdIdsarray of stringsRequired
Missing days and metrics are not zero-filled.
requestedAdIdsarray of stringsRequired
Requested ads.
retrievedAtstring (date-time)Required
When Pluto assembled this read.
rowsarray of objectsRequired
Original ad/day facts; outcomes are never duplicated or allocated to each asset.
rows[].actionValuesmap of string
The value of each action type, in the account currency.
rows[].actionsmap of string
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[].adAccountIdstringRequired
Source Meta ad account.
rows[].adIdstringRequired
Source Meta ad.
rows[].adsetIdstringRequired
Reported ad set.
rows[].attributionstringRequired
Exact provider attribution window.
rows[].campaignIdstringRequired
Reported campaign.
rows[].compositionobjectRequired
rows[].composition.assumedContinuitybooleanRequired
True means matching snapshots assume continuity; intermediate changes were not observed.
rows[].composition.creativeIdstring or nullRequired
Only set for an observed stable bracket; not a delivered dynamic asset ID.
rows[].composition.firstObservedAtstring or nullRequired
Earliest supporting observation time.
rows[].composition.lastObservedAtstring or nullRequired
Latest supporting observation time.
rows[].composition.observationCountintegerRequired
Supporting observations.
rows[].composition.reasonstringRequired
Why composition is stable, mixed or unknown.
rows[].composition.statusstringRequired
Matching observed snapshots, unresolved changes or missing coverage.One of observed_stable, mixed, unknown
rows[].composition.validFromstring or nullRequired
Inferred start of a fully bracketed account-local day; not an exact provider change time.
rows[].composition.validUntilstring or nullRequired
Inferred exclusive end of that bracketed day.
rows[].currencystringRequired
Reported account currency.
rows[].datestring (date)Required
rows[].denominatorsmap of stringRequired
Reported impressions, clicks, linkClicks, purchases and videoViews. No retention curve is inferred.
rows[].fetchedAtstring (date-time)Required
When this latest stored provider fact was fetched; not a point-in-time training snapshot.
rows[].metricsmap of stringRequired
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[].rankingsobject
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[].resultIndicatorstring or nullRequired
Provider result indicator, when reported.
rows[].timezonestringRequired
Reported account timezone used for the day.
sincestring (date)Required
untilstring (date)Required

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/creative-memory/precision/quote

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

intervalobject or null
Required original-video interval, at most 90 seconds. Images require null or omission and the visual method.
interval.endMsintegerRequired
interval.startMsintegerRequired
languagestring or null
Optional ASR language hint. Alignment requires a separately provisioned compatible checkpoint; unsupported fine timing remains unknown.
mediaIdstring (uuid)Required
Already indexed source in this workspace.
methodstringRequired
Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of visual, native_av, word_timing
questionstringRequired
Specific source-grounded question; cannot override model, resource or spending limits.

Response200 OK

allowedbooleanRequired
All requested new work is currently eligible.
correctionHeadIdstring (uuid) or nullRequired
Pinned authorized correction generation; null when none.
creditsobject or nullRequired
credits.analysesintegerRequired
Analysis units paid in credits, 50 credits each.
credits.creditsintegerRequired
The credits they take at most, paid from the organization's pool before the work starts.
expiresAtstring (date-time)Required
Requote after this time.
idstring (uuid)Required
Accept this exact unexpired quote.
imagesintegerRequired
New basic image/card indexing.
maxVideoSecondsnumber or nullRequired
methodstringRequired
Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of visual, native_av, word_timing
policyRevisionstringRequired
Pinned model, extraction and precision policy fingerprint.
publicationIdsarray of strings (uuid)Required
Current non-precision source publications required by this result.
questionstringRequired
Question bound to the quote.
reasonstring or nullRequired
Why it cannot proceed.
remaininginteger or nullRequired
Included analysis units left before this request (on an Enterprise contract every analysis is paid in credits, so this is 0).
reusedCountintegerRequired
Items whose existing work is reused.
sourceRevisionstringRequired
Pinned immutable source object revision.
unitsintegerRequired
New analysis units: 50 credits each (an image; a started video minute is 5).
videoMinutesnumberRequired

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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?"
  }'
POST/creative-memory/precision/requests

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

quoteIdstring (uuid)Required
Exact approved, unexpired precision quote.

Response200 OK

createdAtstring (date-time)Required
Accepted.
errorstring or nullRequired
Actionable failure, if any.
idstring (uuid)Required
Request.
itemsarray of objectsRequired
Selected media and original-media sections.
items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
kindstringRequired
Processing requested.One of index, deep
statusstringRequired
Current execution state, independent of published coverage.
unitsintegerRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
GET/creative-memory/precision/requests/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe request's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

correctionHeadIdstring (uuid) or nullRequired
Pinned authorized correction generation; changed corrections make this result stale.
methodstringRequired
Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of visual, native_av, word_timing
publicationIdstring (uuid) or nullRequired
Supplemental evidence publication, if completed.
publicationIdsarray of strings (uuid)Required
Current non-precision source publications required by this result.
questionstringRequired
Accepted question.
requestobjectRequired
request.createdAtstring (date-time)Required
Accepted.
request.errorstring or nullRequired
Actionable failure, if any.
request.idstring (uuid)Required
Request.
request.itemsarray of objectsRequired
Selected media and original-media sections.
request.items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
request.items[].mediaIdstring (uuid)Required
Media in this workspace.
request.items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
request.jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
request.kindstringRequired
Processing requested.One of index, deep
request.statusstringRequired
Current execution state, independent of published coverage.
request.unitsintegerRequired
New analysis units: 50 credits each (an image; a started video minute is 5).
resultobject or nullRequired
result.coverageobjectRequired
result.coverage.asrobjectRequired
result.coverage.asr.configHashstring or nullRequired
Extraction policy fingerprint.
result.coverage.asr.coveragearray of objectsRequired
Intervals actually examined, in original-source milliseconds.
result.coverage.asr.frameIdsarray of stringsRequired
Examined spatial/frame references; images have no invented time interval.
result.coverage.asr.statusstringRequired
Extractor status, independent of interpretation certainty.One of succeeded, failed, not_applicable, not_requested, unsupported, skipped
result.coverage.asr.warningsarray of stringsRequired
Modality limitations.
result.coverage.audioobjectRequired
result.coverage.audio.configHashstring or nullRequired
Extraction policy fingerprint.
result.coverage.audio.coveragearray of objectsRequired
Intervals actually examined, in original-source milliseconds.
result.coverage.audio.frameIdsarray of stringsRequired
Examined spatial/frame references; images have no invented time interval.
result.coverage.audio.statusstringRequired
Extractor status, independent of interpretation certainty.One of succeeded, failed, not_applicable, not_requested, unsupported, skipped
result.coverage.audio.warningsarray of stringsRequired
Modality limitations.
result.coverage.framesobjectRequired
result.coverage.frames.configHashstring or nullRequired
Extraction policy fingerprint.
result.coverage.frames.coveragearray of objectsRequired
Intervals actually examined, in original-source milliseconds.
result.coverage.frames.frameIdsarray of stringsRequired
Examined spatial/frame references; images have no invented time interval.
result.coverage.frames.statusstringRequired
Extractor status, independent of interpretation certainty.One of succeeded, failed, not_applicable, not_requested, unsupported, skipped
result.coverage.frames.warningsarray of stringsRequired
Modality limitations.
result.coverage.ocrobjectRequired
result.coverage.ocr.configHashstring or nullRequired
Extraction policy fingerprint.
result.coverage.ocr.coveragearray of objectsRequired
Intervals actually examined, in original-source milliseconds.
result.coverage.ocr.frameIdsarray of stringsRequired
Examined spatial/frame references; images have no invented time interval.
result.coverage.ocr.statusstringRequired
Extractor status, independent of interpretation certainty.One of succeeded, failed, not_applicable, not_requested, unsupported, skipped
result.coverage.ocr.warningsarray of stringsRequired
Modality limitations.
result.coverage.shotsobjectRequired
result.coverage.shots.configHashstring or nullRequired
Extraction policy fingerprint.
result.coverage.shots.coveragearray of objectsRequired
Intervals actually examined, in original-source milliseconds.
result.coverage.shots.frameIdsarray of stringsRequired
Examined spatial/frame references; images have no invented time interval.
result.coverage.shots.statusstringRequired
Extractor status, independent of interpretation certainty.One of succeeded, failed, not_applicable, not_requested, unsupported, skipped
result.coverage.shots.warningsarray of stringsRequired
Modality limitations.
result.interpretationobject or nullRequired
result.interpretation.limitationsarray of stringsRequired
result.interpretation.observationsarray of objectsRequired
result.interpretation.observations[].certaintystringRequired
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[].claimstringRequired
result.interpretation.observations[].endMsinteger or nullRequired
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[].evidenceIdsarray of stringsRequired
Supplied evidence IDs that support this claim over its whole span.
result.interpretation.observations[].kindstringRequired
One of hook, demonstration, offer, objection, claim, proof, call_to_action, visual, narrative, audio
result.interpretation.observations[].startMsinteger or nullRequired
Original-media ms of the earliest cited evidence; null for a still image.
result.interpretation.summarystringRequired
What the supplied selection shows and says. Never empty.
result.interpretation.summaryEvidenceIdsarray of stringsRequired
Supplied evidence IDs supporting the summary. At least one.
result.methodstringRequired
Bounded visual inspection, native audio/video inspection, or conditional word alignment.One of visual, native_av, word_timing
result.observationsarray of objectsRequired
Native observations; empty for other methods.
result.observations[].certaintystringRequired
Provider uncertainty, not verified fact.One of tentative, supported
result.observations[].claimstringRequired
Source-grounded native inspection claim.
result.observations[].endMsintegerRequired
Estimated original-source end.
result.observations[].modalitystringRequired
Claimed sensory evidence.One of audio, visual, audio_visual
result.observations[].sourceRefsarray of stringsRequired
Verified delivered-clip references.
result.observations[].startMsintegerRequired
Estimated original-source start.
result.provenanceobject
result.provenance.clipSourceIdstringRequired
Citation for the delivered clip.
result.provenance.deliveryobjectRequired
result.provenance.delivery.assetRefstring (uuid)Required
Original source media.
result.provenance.delivery.audioChannelsinteger or nullRequired
Delivered audio channel count.
result.provenance.delivery.audioClipRangeMsobject or nullRequired
result.provenance.delivery.audioSampleRateinteger or nullRequired
Delivered audio sample rate.
result.provenance.delivery.byteSizeintegerRequired
Delivered clip bytes.
result.provenance.delivery.clipVideoPtsMsarray of integersRequired
Delivered clip frame timestamps.
result.provenance.delivery.contentSha256stringRequired
Original source hash.
result.provenance.delivery.durationMsintegerRequired
Delivered clip duration.
result.provenance.delivery.heightinteger or nullRequired
Delivered video height.
result.provenance.delivery.maxFpsinteger or nullRequired
Clip frame-rate cap; actual decoded timestamps are retained.
result.provenance.delivery.mimeTypestringRequired
Delivered clip media type.
result.provenance.delivery.pipelineRevisionstringRequired
Pinned ML extraction revision.
result.provenance.delivery.policystringRequired
Clip construction policy.
result.provenance.delivery.requestedIntervalobjectRequired
result.provenance.delivery.schemaVersionstringRequired
Clip transport contract version.
result.provenance.delivery.sha256stringRequired
Delivered clip hash.
result.provenance.delivery.sourceAudioChannelsinteger or nullRequired
Source audio channel count.
result.provenance.delivery.sourceAudioCoveragearray of objectsRequired
Actual audio coverage; gaps remain explicit.
result.provenance.delivery.sourceAudioRangeMsobject or nullRequired
result.provenance.delivery.sourceContainerStartMsintegerRequired
Source container start timestamp; not silently treated as zero.
result.provenance.delivery.sourceDurationMsintegerRequired
Original source duration.
result.provenance.delivery.sourceOffsetMsintegerRequired
Original-source offset added to clip-relative timestamps.
result.provenance.delivery.sourceRevisionstringRequired
Immutable source object revision.
result.provenance.delivery.sourceVideoPtsMsarray of integersRequired
Corresponding source frame timestamps.
result.provenance.delivery.videoClipRangeMsobject or nullRequired
result.provenance.delivery.warningsarray of stringsRequired
Clip limitations.
result.provenance.delivery.widthinteger or nullRequired
Delivered video width.
result.provenance.inspectionIsNotExhaustiveCoveragebooleanRequired
True: no claim that every event was examined.
result.provenance.processingstringRequired
Provider processing mode.
result.provenance.requestedFpsintegerRequired
Requested provider video sampling rate; does not certify coverage.
result.provenance.requestedResolutionstringRequired
Requested provider media resolution.One of LOW, MEDIUM, HIGH
result.provenance.sourceFingerprintstringRequired
Original source fingerprint.
result.provenance.timebasestringRequired
Converted original source clock.One of original_source_ms
result.provenance.timingMethodstringRequired
Native model boundaries remain estimates.One of model_estimate_not_forced_alignment
result.publicationIdsarray of strings (uuid)Required
Current non-precision source publications required by this result.
result.questionstringRequired
Explicit question answered.
result.sourceRevisionstringRequired
Pinned immutable source revision.
result.statusstringRequired
Result coverage, separate from request execution.One of ready, partial
result.timingarray of objectsRequired
Raw transcript timing and separately recorded alignment.
result.timing[].alignmentobject or nullRequired
result.timing[].alignment.frameResolutionMsnumber
Model emission spacing, not guaranteed boundary accuracy.
result.timing[].alignment.languagestring or nullRequired
ASR language used to select a reviewed compatible aligner.
result.timing[].alignment.methodstringRequired
Bounded local CTC alignment; does not verify transcript correctness.One of local_ctc_forced_alignment_v1
result.timing[].alignment.normalizationstringRequired
Explicit transcript-to-vocabulary normalization policy.
result.timing[].alignment.statusstringRequired
Alignment execution and supported-token coverage.One of succeeded, partial, unsupported, failed
result.timing[].alignment.warningsarray of stringsRequired
Alignment limitations and failures.
result.timing[].alignment.wordsarray of objectsRequired
Words retain their raw text; unsupported or unreliable timing remains null.
result.timing[].endMsintegerRequired
Raw original-source segment end.
result.timing[].idstringRequired
Original ASR source reference.
result.timing[].languagestring or nullRequired
Reported ASR language; unknown stays null.
result.timing[].rawTimingMethodstring or nullRequired
Raw ASR timing provenance.
result.timing[].rawWordsarray of objects or nullRequired
Original ASR word estimates, preserved separately from alignment.
result.timing[].rawWords[].endMsintegerRequired
Raw estimated original-source end.
result.timing[].rawWords[].pnumberRequired
ASR token score; not forced alignment.
result.timing[].rawWords[].startMsintegerRequired
Raw estimated original-source start.
result.timing[].rawWords[].wstringRequired
Raw ASR token.
result.timing[].startMsintegerRequired
Raw original-source segment start.
result.timing[].textstringRequired
Unmodified transcript segment.
result.warningsarray of stringsRequired
Unknowns and limitations.
sourceRevisionstringRequired
Accepted immutable source revision.
stalebooleanRequired
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-After seconds. 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"
POST/creative-memory/precision/requests/{id}/cancel

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe request's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

createdAtstring (date-time)Required
Accepted.
errorstring or nullRequired
Actionable failure, if any.
idstring (uuid)Required
Request.
itemsarray of objectsRequired
Selected media and original-media sections.
items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
kindstringRequired
Processing requested.One of index, deep
statusstringRequired
Current execution state, independent of published coverage.
unitsintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/precision/requests/d2cf1df9-efd7-4c87-bd42-e589aaca3089/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: cab66c61-59bd-4088-9576-c9cbb20af782"
POST/creative-memory/quote

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

itemsarray of objectsRequired
1–100 new or previously read media/sections; reused stages use no credits or allowance.
items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
kindstringRequired
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

Response200 OK

allowedbooleanRequired
All requested new work is currently eligible.
creditsobject or nullRequired
credits.analysesintegerRequired
Analysis units paid in credits, 50 credits each.
credits.creditsintegerRequired
The credits they take at most, paid from the organization's pool before the work starts.
expiresAtstring (date-time)Required
Requote after this time.
idstring (uuid)Required
Accept this exact unexpired quote.
imagesintegerRequired
New basic image/card indexing.
maxVideoSecondsnumber or nullRequired
reasonstring or nullRequired
Why it cannot proceed.
remaininginteger or nullRequired
Included analysis units left before this request (on an Enterprise contract every analysis is paid in credits, so this is 0).
reusedCountintegerRequired
Items whose existing work is reused.
unitsintegerRequired
New analysis units: 50 credits each (an image; a started video minute is 5).
videoMinutesnumberRequired

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
GET/creative-memory/requests

List Creative Memory requests

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalPrevious nextAfter UUID.
limitquerystringOptionalPage size, default 50.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].createdAtstring (date-time)Required
Accepted.
items[].errorstring or nullRequired
Actionable failure, if any.
items[].idstring (uuid)Required
Request.
items[].itemsarray of objectsRequired
Selected media and original-media sections.
items[].items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
items[].jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
items[].kindstringRequired
Processing requested.One of index, deep
items[].statusstringRequired
Current execution state, independent of published coverage.
items[].unitsintegerRequired
New analysis units: 50 credits each (an image; a started video minute is 5).
nextAfterstring or integer or null
Pass as the cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/requests" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/creative-memory/requests

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

quoteIdstring (uuid)Required
Approved, unexpired quote.

Response200 OK

createdAtstring (date-time)Required
Accepted.
errorstring or nullRequired
Actionable failure, if any.
idstring (uuid)Required
Request.
itemsarray of objectsRequired
Selected media and original-media sections.
items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
kindstringRequired
Processing requested.One of index, deep
statusstringRequired
Current execution state, independent of published coverage.
unitsintegerRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/creative-memory/requests/{id}/cancel

Cancel unfinished Creative Memory work

Cancels pending work and releases unused reservations; successfully published stages remain available. Retrying does not refund or charge twice.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe request's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

createdAtstring (date-time)Required
Accepted.
errorstring or nullRequired
Actionable failure, if any.
idstring (uuid)Required
Request.
itemsarray of objectsRequired
Selected media and original-media sections.
items[].endMsinteger or null
Optional exclusive section end in original-media milliseconds.
items[].mediaIdstring (uuid)Required
Media in this workspace.
items[].startMsinteger or null
Optional inclusive section start in original-media milliseconds; give endMs too.
jobIdstring (uuid) or nullRequired
Durable job; use get_job or wait_for_job.
kindstringRequired
Processing requested.One of index, deep
statusstringRequired
Current execution state, independent of published coverage.
unitsintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/creative-memory/requests/d2cf1df9-efd7-4c87-bd42-e589aaca3089/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 42d64224-15d1-4dd8-876f-c84abe45d96f"
GET/creative-memory/search

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.

Permission: read

Parameters

NameTypeRequiredDescription
qquerystringOptionalVerbatim query.
tagsquerystringOptionalTag (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.
afterquerystringOptionalPrevious nextAfter cursor.
limitquerystringOptionalBounded page size.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

coverageobject
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.indexedintegerRequired
Files in scope Creative Memory has read: their evidence is searched.
coverage.totalintegerRequired
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).
incompletearray of strings
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.
itemsarray of objectsRequired
This result page.
items[].kindstringRequired
Media kind.
items[].matchesarray of objectsRequired
Matching cited evidence/moments.
items[].matches[].endMsinteger or nullRequired
Original-media end.
items[].matches[].idstringRequired
Source reference.
items[].matches[].originstring
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[].sourcestringRequired
Evidence modality/source.
items[].matches[].startMsinteger or nullRequired
Original-media start.
items[].matches[].textstringRequired
Observed evidence.
items[].mediaIdstring (uuid)Required
Matching media.
items[].namestringRequired
Media name.
items[].statusstringRequired
In-depth readiness.
items[].summarystring or nullRequired
Published interpretation.
modestringRequired
Retrieval mode; partial availability is explicit. names when the search couldn't finish in time and lists the files whose names match.
nextAfterstring or nullRequired
Next page cursor.
resultLimitintegerRequired
Maximum results retained for this search snapshot.
semanticstringRequired
Meaning-based matching: used, not requested (browsing), off for quoted phrases, or unavailable (text matching only).One of used, not_requested, literal, unavailable
truncatedbooleanRequired
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-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
  • 503search_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: wait Retry-After seconds and ask again.
curl "$PLUTO_API/creative-memory/search" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/creative-memory/usage

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

availablebooleanRequired
Whether new processing is available.
deepobjectRequired
deep.limitnumber or nullRequired
deep.remainingnumber or nullRequired
deep.reservednumberRequired
deep.usednumberRequired
imagesobjectRequired
images.limitnumber or nullRequired
images.remainingnumber or nullRequired
images.reservednumberRequired
images.usednumberRequired
maxDeepVideoSecondsnumber or nullRequired
periodEndstring or nullRequired
Trial expiry or monthly renewal.
periodKindstringRequired
One trial window or a UTC calendar month.One of trial, monthly
periodStartstring (date-time)Required
Allowance window starts.
unavailableCodestring or nullRequired
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
unavailableReasonstring or nullRequired
Missing processing availability or agreed terms.
videoMinutesobjectRequired
videoMinutes.limitnumber or nullRequired
videoMinutes.remainingnumber or nullRequired
videoMinutes.reservednumberRequired
videoMinutes.usednumberRequired

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/creative-memory/usage" \
  -H "Authorization: Bearer $PLUTO_KEY"