Creative - Interchange API

Overview

A Creative in v2 is a creative manifest — a structured bundle containing uploaded assets (images, video, HTML, VAST tags), an optional brief, brand info auto-resolved from the campaign’s advertiser, and a target ADCP format. Manifests are nested under campaigns and propagate to media buys at execution time.

New in v2: creatives are no longer stored at the advertiser level and referenced by campaigns. They are created directly under a campaign at /api/v2/buyer/campaigns/:campaignId/creatives/.... The model is also fully manifest-aligned with the AdCP creative manifest spec.

Field-name exception: Creative manifests use snake_case field names (creative_id, campaign_id, format_id, template_id, brand_domain, target_format_ids) because they are passed through verbatim to the ADCP wire-format. This is an intentional exception to v2’s general camelCase convention — see the migration guide for context.

Why this changed

V1 treated creatives as advertiser-level assets reused across campaigns. V2 tightens the model so:

Each campaign sees exactly the formats its selected products require (creativeFormats.required)
Asset uploads happen in a single multipart request with the manifest metadata
Format and template auto-detection runs against the campaign’s product mix
Tracking macros and brand info are resolved from the campaign + advertiser context

The result is fewer mismatches between selected products and uploaded creatives, and a cleaner per-campaign creative library.

Key fields

Field	Type	Notes
`creative_id`	string	Manifest ID
`campaign_id`	string	Owning campaign
`name`	string	Human-readable name
`message`	string	Optional creative brief / direction text
`template_id`	string	Creative template (`display_image`, `display_html`, `video_standard`, vendor tags, etc.)
`format_id`	object	`{ agent_url, id }` — legacy (v1 named-format) format reference. Mutually exclusive with `format_kind`.
`format_kind`	string	Canonical (AdCP 3.1) format selector — a bare enum (`image`, `video_vast`, `video_hosted`, …) with no `agent_url`. Video/audio duration rides in `params` (`duration_ms_exact` / `duration_ms_range`), not on `format_id`. See the glossary.
`target_format_ids`	array	Formats from campaign products this manifest can serve
`brand_domain`	string	Auto-resolved from the campaign’s advertiser
`assets`	array	Uploaded assets (id, type, MIME, public URL, source)
`preview_url`	string	URL to processed HTML preview hosted on GCS
`tracking`	object	Auto-generated impression and click tracker URLs
`sync_status`	object	`{ synced, agent_count, last_synced_at }` across sales agents
`frequencyCaps`	array	Buyer-defined caps on this creative

Asset types

V2 assets cover the full ADCP type spectrum:

Type	Purpose
`IMAGE`	JPEG, PNG, GIF, WebP, SVG
`VIDEO`	MP4, WebM, QuickTime
`AUDIO`	MP3, WAV, OGG
`HTML`	Inline content or hosted URL
`JAVASCRIPT` / `CSS`	Companion script and style assets
`VAST`	VAST tag (URL or inline XML) — renamed from v1’s `VIDEO_VAST`
`URL`	Clickthrough, tracker pixel, or VAST URL with explicit `url_type`
`FONT` / `LOGO` / `DOCUMENT` / `TEXT`	Supporting assets

URL assets are typed via url_type: CLICKTHROUGH, TRACKER_PIXEL, TRACKER_SCRIPT, or VAST. Webhook assets enable server-side dynamic content rendering (DCO) with HMAC or API-key signing.

Lifecycle

Discover required formats

GET /api/v2/buyer/campaigns/:campaignId/creatives/templates returns available templates plus the selected products’ required formats. V2-native declarations are returned in campaign_format_options; legacy format references remain in campaign_format_ids for compatibility. Each product’s requirements are also broken out under campaign_products. The legacy named-format registry across agents is available at GET /api/v2/buyer/formats.

Create the manifest

POST a multipart request with files + JSON metadata. Scope3 auto-classifies assets, processes HTML to rewrite local references to CDN URLs, inserts ADCP macros, and generates a preview.

Validate coverage

GET /api/v2/buyer/campaigns/:id returns creativeFormats: { required, covered, missing }. Upload more manifests until missing is empty.

Propagate to media buys

On campaign execute, the manifests sync to each sales agent for the formats they support. A ready manifest is registered for delivery in the same transaction as its assets, so it cannot disappear between upload and assignment. Sync status is reflected in sync_status on each manifest.

Update or replace

PUT the manifest with new files, deletions, or reclassifications. Updates flow back to media buys.

Media-buy compatibility results

When a media buy inherits creatives from its campaign, Scope3 checks each creative against the selected products before delivery. An inherited creative that cannot serve those products is omitted and reported in creative_compatibility_warnings with a status of incompatible or unresolved and a reason. Older creative records that do not contain a usable format are reported in legacy_creatives_excluded. Historical static-image labels such as display_300x250, banner_300x250, and display_300x250_nongenerative can serve a product’s same-sized display_300x250_image placement without retyping the saved creative. Scope3 sends the product’s advertised format reference and still checks the creative’s asset type and dimensions before delivery. Other legacy-format differences remain incompatible rather than being widened by format family. Scope3 preserves an imported legacy format label for traceability, but a saved creative’s canonical format_kind is authoritative for campaign and product matching. New saved creatives must resolve a canonical kind. If an older creative’s assets, media type, dimensions, and import provenance do not identify one format kind deterministically, Scope3 quarantines it for explicit upgrade instead of guessing. Seller-specific format references are applied only when the creative is adapted for that seller; they do not change the saved master. If a create-media-buy request explicitly names an incompatible or unresolved creative, the request is rejected instead of creating a buy that silently drops it. Integrations should surface these response fields so a buyer can replace or correct the creative before launch. For creatives your integration creates, use the canonical format_kind field. It never contains an agent URL. Scope3 only preserves a URL-bearing format_id when an external third-party system explicitly supplied that legacy reference.

Conversational creative sessions

Creative sessions are the agent-native path for buyers who want to generate, compare, refine, validate, and save creatives without handling manifest details directly. The intended user flow is:

Idea — the buyer describes the channel, audience, goal, and source assets.
Draft gallery — a creative adapter returns multiple draft variants for human review.
Refine — the buyer gives natural-language feedback like “make the book more prominent” or “less busy.”
Evaluate — draft checks are advisory; final hard/blocking checks stop finalization.
Finalize — the approved leaf is saved as a campaign creative manifest.

Use POST /api/v2/buyer/campaigns/:campaignId/creative-sessions to start a session. The response is designed for MCPUI and includes the draft variants[], asset_store, renderer_capabilities, rendering_model, staged evaluator badges, and format_renders[] once a final is approved.

Creative sessions are review workflows. They do not replace campaign creative manifests. Finalization is the transition point where a selected draft/refinement becomes a normal campaign creative with creative_id, format_id, assets, preview, and sync status.

Required placement shapes

When a campaign has required placements, a format_renders[] tile is produced per placement at its real size. A placement with an extreme aspect ratio — a wide leaderboard or a tall skyscraper — only renders at its true shape if the generator can compose that ratio natively. Gemini and FAL do; OpenAI generates a fixed set of shapes and crops to fit. If your session’s connected generator would crop such a placement and you have also connected a native-ratio generator (Gemini or FAL) for that advertiser, that one placement is rendered on the native-ratio generator instead — on your own connected key for it, billed to that vendor account, the same as any generation on that provider. Other placements in the session stay on your session generator. When no native-ratio generator is connected, the placement still renders on the session generator with an advisory note that it may crop; connect one to fix the shape.

Asset lifecycle

Creative production uses three related but distinct asset layers:

Layer	What it is	Stored as	How to use it
Source asset	Buyer-supplied input such as a book cover, product photo, logo, DAM URL, catalog image, audio file, or reference image	`source_asset` and `asset_store.assets[]` inside the creative session	Treat as raw input. Preserve locked assets exactly; track role, provenance, rights, checksum, dimensions, and render crop/mask metadata when available.
Draft variant	A generated or composited creative direction for review	`variants[]` with preview URL, quality, status, lineage, and evaluator checks	Use for exploration. Drafts may be discarded, branched, or refined. They are not campaign creatives until finalized.
Final creative	The approved execution saved to the campaign	Creative manifest under `/campaigns/:campaignId/creatives`	Use for delivery. It carries the final render, linked assets, text assets, ADCP format ID, tracking, preview, and sync status.

For locked product, package, logo, or book-cover assets:

Set locked_asset: true, can_transform: false, role: "product" (or the closest role), and specific preservation_notes.
Keep provenance separate from rights. source: "upload" or source: "dam" says where the asset came from; rights.status says whether it is cleared.
rights.status: "unknown" is a non-blocking review warning for final approval. restricted or expired blocks finalization.
If the source image includes studio background or whitespace, provide render_crop, subject_bounds, or a transparent cutout/mask when available. Cropping is a preservation-safe fallback; a real cutout produces cleaner final compositions.

Seller-specific versions

The campaign’s selected products determine which seller formats need coverage. Use the creative template/format endpoints before and after finalization:

GET /api/v2/buyer/campaigns/:campaignId/creatives/templates shows required campaign formats and available templates.
Start a creative session against the best matching creative adapter and target format.
Finalize the chosen direction into a creative manifest.
Re-check creativeFormats on GET /api/v2/buyer/campaigns/:campaignId.
If creativeFormats.missing still contains seller formats, generate or adapt seller-specific manifests for those formats.

Seller-specific versions should keep a common creative direction and source-asset lineage, but each saved manifest must match the actual seller format it covers. For example, the same “Wimbledon book hero” direction may need separate square image, portrait story, audio, video, or HTML executions depending on the selected products. format_renders[] is the review surface for publisher/format previews. It helps a buyer inspect what the final creative looks or sounds like in a particular canonical renderer. The actual delivery object remains the saved creative manifest and its synced seller-specific format coverage.

Performance loop

Creative work does not end at finalization. The full performance cycle is:

Create or update campaign goals — use performanceConfig on the campaign when optimizing toward events or metrics.
Launch with format coverage — execute only after required creative formats are covered.
Collect delivery and outcome data — use reporting plus conversion/measurement ingestion (log_event, measurement data sync, or measurement records depending on integration).
Compare creative performance — inspect performance by campaign, media buy, package, and creative where reporting dimensions are available.
Iterate — duplicate or start a new creative session from the winning direction, then refine the creative based on observed performance and seller feedback.

The Anjali/The Shift prototype exercises the creative build, preview, evaluator, and finalization loop. A complete performance cycle also needs live delivery, measurement ingestion, reporting by creative, and an optimization decision that feeds a new creative iteration.

Evaluator strategy

Creative evaluators answer different questions at different moments. Treat them as a selected set of checks, not a single score.

Evaluator type	Question it answers	Typical stage
Core readiness	Is there a renderable preview and valid manifest structure?	Draft, final
Asset fidelity	Did locked assets stay intact, and are rights/provenance usable?	Draft, final
Brand/brief	Does the direction fit the campaign brief and brand guidance?	Draft, final
Format/seller	Does this execution satisfy the selected seller or publisher format?	Final
Policy/safety	Is there policy, claims, legal, or safety risk?	Final
Performance	Did it actually work after delivery?	Postflight

Draft evaluator warnings should guide refinement. Final hard/blocking failures prevent finalization. Non-blocking final warnings, such as unknown source-asset rights, should be shown as review notes. Performance evaluators should only run after delivery/reporting data exists; pre-flight checks cannot prove a creative will win. Longer term, evaluator selection should come from the creative session context:

source assets and lock/rights metadata
modality and renderer type
campaign brief and brand guidance
selected seller formats and publisher policies
available adapter/seller evaluator capabilities
postflight reporting and measurement data

Common operations

Create a creative manifest (multipart)

The endpoint accepts a metadata JSON field plus files[] form fields:

curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/create \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'metadata={
    "name": "Q2 hero video",
    "message": "30s product reveal — premium tone, 2-second hook",
    "template_id": "video_standard",
    "url_asset": { "url": "https://acme.com/promo", "url_type": "CLICKTHROUGH" },
    "assets": [
      { "filename": "hero-30s.mp4", "asset_type": "VIDEO", "label": "main_video" }
    ]
  };type=application/json' \
  -F "files=@hero-30s.mp4" \
  -F "files=@companion-banner.png"

curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/create \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'metadata={
    "name": "VAST premium",
    "template_id": "video_vast",
    "url_asset": { "url": "https://ad.doubleclick.net/ddm/vast/...", "url_type": "VAST" }
  };type=application/json'

Creative creation is a single multipart request: a JSON metadata field plus zero or more files parts (-F "files=@..."). The server accepts up to the configured MAX_FILE_COUNT files per request and pairs each file with the matching assets[].filename in the metadata.

File limits: 50 MB per file, 20 files per request. Allowed MIME types include images (JPEG, PNG, GIF, WebP, SVG, HEIC), video (MP4, WebM, QuickTime), audio (MP3, WAV, OGG), HTML/CSS/JS, fonts, PDF, and XML/markdown.

List manifests

curl "https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creativeManifest?take=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Filters: search, includeFrequencyCaps. Pagination: take, skip.

Get / update / delete

curl https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X PUT https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -F 'metadata={
    "delete_asset_ids": ["asset_old"],
    "new_assets": [{ "filename": "v2.mp4", "asset_type": "VIDEO" }]
  };type=application/json' \
  -F "files=@v2.mp4"

curl -X DELETE https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Render an ADCP preview

curl -X POST https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef/preview \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Calls the ADCP agent’s preview_creative tool to render at native format dimensions. Useful for validation before publisher submission.

Advertiser-scoped creative listing

GET /api/v2/buyer/advertisers/:advertiserId/creatives returns all creatives scoped to the advertiser — both promoted library creatives (evergreen/reference role) and flight-specific creatives attached to any campaign under this advertiser. A creative inherits the campaign’s advertiser_id at creation time, so it appears in this list regardless of campaign attachment. Use ?promoted=true to filter to library creatives only (those explicitly saved with a role). Without this filter, the full set is returned — including creatives uploaded via the campaign-level creative dashboard that have not been promoted. The advertiser creative listing also accepts ?search, ?role, ?source, ?format_kind, ?asset_type, and ?dimensions filters alongside standard ?take/?skip pagination.

Advertiser library: assign and unassign

Creatives can be saved to an advertiser library (promoted to evergreen or reference role) and then attached to campaigns via the advertiser-scoped endpoints:

Method	Path	Purpose
`POST`	`/api/v2/buyer/advertisers/:advertiserId/creatives/save-to-library`	Promote creatives to the advertiser library with a role
`POST`	`/api/v2/buyer/advertisers/:advertiserId/creatives/:creativeId/campaigns`	Assign a library creative to a campaign
`DELETE`	`/api/v2/buyer/advertisers/:advertiserId/creatives/:creativeId/campaigns/:campaignId`	Remove a library creative from a campaign

Ownership validation

Both assign and unassign enforce advertiser ownership: the creative and the target campaign must belong to the same advertiser. If they belong to different advertisers, the endpoint returns HTTP 422 with error code INVALID_REQUEST.

{
  "error": "Creative belongs to a different advertiser than the campaign.",
  "code": "INVALID_REQUEST",
  "field": "advertiserId"
}

A creative with no advertiser_id (not yet scoped to an advertiser) can be assigned to any campaign, and the backfill sets its advertiser_id to match the campaign’s.

Collection fan-out

When you assign a collection to a campaign, members whose advertiser_id conflicts with the campaign’s advertiser are silently skipped. The response includes an ownership_excluded count so you can detect this. Check that all expected creatives appear in the campaign after a collection assign, and promote any skipped creatives to the correct advertiser before retrying.

Format coverage on the campaign

When you GET /api/v2/buyer/campaigns/:id, the response includes:

"creativeFormats": {
  "required": [{ "format_kind": "video_hosted" }],
  "covered":  [{ "format_kind": "video_hosted" }],
  "missing":  []
}

missing is the prompt to upload more creatives. Coverage is computed against the formats every selected product needs.

Tracking macros

When the format supports it, Scope3 auto-injects:

An impression tracker URL as a TRACKER_PIXEL URL asset
A click tracker URL that wraps the original clickthrough — the original is preserved in the rurl query parameter

ADCP universal macros ({CAMPAIGN_ID}, {DEVICE_TYPE}, {COUNTRY}, etc.) are filled at impression time. The tracking.supported_macros array on the manifest response lists which macros the format supports.

Only one clickthrough URL per manifest. If multiple URL assets are flagged url_type: CLICKTHROUGH, manifest creation fails.

The injected impression and click trackers fire to ping.interchange.io — Scope3’s own measurement domain in production (/agentic/imp for impressions, /agentic/clk for clicks). Because it is Scope3’s domain rather than a registered third party, Google Ad Manager doesn’t recognize it as a known ad-tech vendor (see below). It powers impression counting, frequency capping, emissions measurement, and conversion attribution.

What the tracker carries

The impression URL carries identifiers and tokens — never raw PII:

Param	Meaning
`dsid`	Dataset ID — links the impression to the advertiser’s conversion-attribution dataset
`cid`	Creative ID
`camp`	Campaign ID
`advid`	Advertiser ID
`mb`	Media buy ID, filled at serve time
`pkg`	Package ID — left blank on synced creatives, which can map to multiple packages
`axem`	Emissions measurement token, filled at serve time
`tmpx`	HPKE-encrypted exposure token for frequency capping, filled at serve time (see TMP)
`cb`	Cachebuster

The click tracker carries the same identifiers and preserves the original clickthrough in the rurl parameter.

axem and tmpx are filled by the TMP Router and are populated only when the publisher has connected TMP — without it they resolve to empty, and the pixel still counts impressions but carries no emissions or frequency-cap signal.

Where the format or advertiser tracking config enables them, the tracker URL includes consent macros as ad-server placeholders — gdpr (whether GDPR applies), gdpr_c (the TCF consent string), and us_p (the US Privacy string). The ad server fills them from the user’s consent state at serve time and forwards them to the endpoint. These are the only consent signals the pixel carries today; there is no GPP (Global Privacy Platform) string.

Clearing the Google Ad Manager “unknown ad technology” warning

When a creative is trafficked through Google Ad Manager, this clearing step is the publisher’s action (a GAM admin), not the buyer’s. GAM scans the creative for ad technology URLs and flags any domain it doesn’t recognize on Google’s Ad Technology Providers list. Because ping.interchange.io is a Scope3 measurement domain, it surfaces under Associated ad technology providers as an unknown URL with the note “We found unknown URLs that may affect serving eligibility.” When the network has Check reservation creatives for user consent enabled, an unrecognized domain blocks the creative from serving — including non-personalized requests — in the EEA, the UK, and Switzerland; the Brazil (LGPD) block applies regardless of that setting. The creative serves normally everywhere else. To clear it, the publisher adds ping.interchange.io as a custom ad partner URL in the network’s EU user consent settings (reachable from the Go to settings link on the warning; the page requires specific GAM permissions, as the warning notes). Selecting “No ad technology providers to declare” does not clear a URL GAM has already detected in the creative.

Format catalog

To inspect formats required by the campaign’s selected products:

Endpoint	Purpose
`GET /api/v2/buyer/campaigns/:campaignId/creatives/templates`	List the deduplicated V2 `format_options`, legacy format IDs, per-product requirements, and available templates for the campaign.
`GET /api/v2/buyer/formats`	Cross-agent legacy named-format registry (all legacy format IDs discovered from sales agents).
`GET /api/v2/buyer/formats/:agentUrl/:formatId`	Format details for a specific format on a specific agent.

Propagation to media buys

At campaign execute, the manifest is synced to each sales agent that supports its format_id. The same manifest can serve multiple media buys; later updates re-sync. Use sync_status to confirm publishers have received the latest version.

Creative transport modes

Interchange chooses the creative transport mode per sales agent:

Creative library sync — sellers that advertise a creative library through creative.has_creative_library: true receive manifests through sync_creatives, and packages reference them with creative_assignments.
Inline creative delivery — sellers that advertise creative.has_creative_library: false receive the creative manifest inline on each package that needs it.

For legacy or unknown capabilities (creative.has_creative_library is null or absent), Interchange falls back to the seller’s advertised tools and uses sync_creatives when available. If sync_creatives fails and the seller allows inline creatives, Interchange falls back to inline package delivery for that seller. If the seller is library-only and sync_creatives fails, the media-buy create or update request fails synchronously instead of silently continuing.

Campaign

Owning campaign — formats come from its products

Brand

Brand info auto-resolved from the advertiser

​Overview

​Why this changed

​Key fields

​Asset types

​Lifecycle

​Media-buy compatibility results

​Conversational creative sessions

​Required placement shapes

​Asset lifecycle

​Seller-specific versions

​Performance loop

​Evaluator strategy

​Common operations

​Create a creative manifest (multipart)

​List manifests

​Get / update / delete

​Render an ADCP preview

​Advertiser-scoped creative listing

​Advertiser library: assign and unassign

​Ownership validation

​Collection fan-out

​Format coverage on the campaign

​Tracking macros

​Measurement endpoint and EU consent

​What the tracker carries

​Consent signals

​Clearing the Google Ad Manager “unknown ad technology” warning

​Format catalog

​Propagation to media buys

​Creative transport modes

​Related concepts

Campaign

Brand

Overview

Why this changed

Key fields

Asset types

Lifecycle

Media-buy compatibility results

Conversational creative sessions

Required placement shapes

Asset lifecycle

Seller-specific versions

Performance loop

Evaluator strategy

Common operations

Create a creative manifest (multipart)

List manifests

Get / update / delete

Render an ADCP preview

Advertiser-scoped creative listing

Advertiser library: assign and unassign

Ownership validation

Collection fan-out

Format coverage on the campaign

Tracking macros

Measurement endpoint and EU consent

What the tracker carries

Consent signals

Clearing the Google Ad Manager “unknown ad technology” warning

Format catalog

Propagation to media buys

Creative transport modes

Related concepts