Creative - Apostra

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. Delivery is campaign-scoped: a manifest reaches a media buy through the campaign it is attached to.

New in v2: the campaign is the default home for a creative. Creatives are created directly under a campaign at /api/v2/buyer/campaigns/:campaignId/creatives/..., rather than being maintained as an advertiser-level catalog that campaigns reference. The model is also fully manifest-aligned with the AdCP creative manifest spec.

Advertiser-level creatives still exist, as a staging and reuse shelf rather than the delivery model. You can create a master under an advertiser before any campaign exists, list an advertiser’s creatives, and promote a creative to the advertiser library — see Advertiser-scoped creative listing and Advertiser library: assign and unassign below. An advertiser-level master carries advertiser_id with no campaign_id and never delivers until it is assigned to a campaign.

Field-name exception: Creative manifests use snake_case field names (creative_id, campaign_id, format_id, format_kind, format_option_ref, 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 the advertiser-level catalog as the primary home for a creative, reused across campaigns. V2 makes the campaign the default home 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
`preview_revision`	string	Exact opaque revision of the buyer-preview projection
`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) selector. New create input uses either this field or canonical identity, never both. A persisted imported manifest may retain it as provenance alongside `format_kind`; in that case the canonical identity is authoritative and the URL is not dispatched.
`format_kind`	string	Canonical (AdCP 3.1) format selector — a bare enum (`image`, `video_vast`, `video_hosted`, …) with no `agent_url`. It may be accompanied by `format_option_ref`. Video/audio duration rides in `params` (`duration_ms_exact` / `duration_ms_range`), not on `format_id`. See the glossary.
`params`	object	Validated parameters retained with canonical identity. A URL-free `image` response includes positive whole-number `width` and `height` here and omits a synthetic `format_id`.
`format_option_ref`	object	Product- or publisher-scoped canonical option `{ scope, format_option_id, publisher_domain? }` that accompanies `format_kind`. It contains no agent URL and is mutually exclusive with a legacy outbound `format_id` selector.
`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	Manifest-local processed preview URL; provider placement previews use the separate preview action below
`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`
`ZIP`	Inspected HTML5 bundle, stored intact with its entry point and declared size
`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.

Uploaded assets and assembled Creatives

The upload Task and the Creative library hold different things. The Task puts private JPEG, PNG, or MP4 bytes into managed storage. During transport it uses an expiring opaque asset_ref; successful advertiser-scoped finalization requires and returns a durable asset_id for the advertiser’s asset library and retains the original filename as its display name. After finalization, the Task records a conversation receipt with the asset ID when one exists, saved name and tags, content type, byte size, digest, and any verified video facts. For a provider-scoped upload without a reusable Library asset ID, the digest is byte identity for the receipt only: it is not an assetId or sourceUid, cannot be passed to save_creative or provider adoption, and does not imply that later attachment is possible. On external hosts, that Task stays open after the receipt so its private continuation reference remains available for any separately requested follow-up; close the Task when no follow-up is needed. The receipt reports the upload only; creating or attaching a Creative, syncing data, contacting a provider, and delivering media still require a separate request. The transport asset_ref, provider identities, signed upload URLs, storage paths, delivery_url, and source_uid are excluded from the receipt.

Browse an advertiser’s Creative Library

In Apostra, select an advertiser and then choose Manage → Creatives. You can also ask Murph to show me my creatives after selecting the advertiser. Both paths open the same Creative Library and show the advertiser name and ID at the top. The Library stays within that advertiser if the surrounding workspace changes or you reload the page. The Creative Library opens in a list grouped by Creative format, with Creatives that do not have a format in Uncategorized at the end of the list. Choose the grid toggle to switch layouts for the current browser session. If no loaded Creative has a format, the Library shows one ungrouped list and does not offer format grouping. Select a Creative or Asset to open a previewer beside the list on wide layouts and in a sheet on narrow ones. The list keeps its search, filters, grouping, and scroll position while the previewer shows the available preview, summary facts, and attachment choices. Close it with Escape or Back to creatives to continue browsing. Opening Creatives from a campaign or from a link shared by your agent opens the same Library with that campaign selected. Existing Campaign Creative Assets bookmarks also move to this shared Library instead of opening the retired screen. Apostra restores the advertiser and campaign when you reload a valid link. A campaign or Creative that does not belong to the selected advertiser, or that you cannot access, is refused rather than opened under a different advertiser. Campaign focus lists the Creatives currently attached to that campaign and supports text search. Choose All advertiser Creatives to browse reusable Creatives, open one, and attach it to the selected campaign. Creative requirements opens the campaign’s current format requirements and mapping task. Those requirements come from the signed format declarations on the campaign’s selected Products. Uploading a file still creates an independent Library asset; you can then assemble a Creative from that asset and attach the saved Creative to the campaign. Preview remains tied to the exact saved Creative revision. Use All Creatives for every visible, non-archived Creative owned by the advertiser. Use Promoted shelf for the smaller set marked for reuse. The current view, search text, number loaded, and total remain visible. If more results are available, the Library says the list is incomplete and lets you load the next page. Opening a Creative loads its exact saved revision through Apostra’s preview origin. If the Creative changes, refresh the Library before opening the new revision. Upload asset starts the existing upload Task; completing that Task adds an asset, not an assembled Creative. Product selection remains required before assembling a new Creative. The Catalogs tab lists the advertiser’s connected catalog feeds beside Creatives and Assets. Each card shows its item count, source, most recent sync, and whether the feed is Healthy or Stale (with the reason). Connect a catalog and Open take you to the existing catalog manager; Build creatives is shown as a forthcoming workflow and does not start work yet. For an object response instead of the visual Library, use V3 search({kind: "creative", filter: {advertiserId}}). Use V3 search({kind: "creative_asset", filter: {advertiserId}}) to find active assets, optionally filtering by text, media kind, or tags. Use get({kind: "creative_asset", id: assetId, sourceId: advertiserId}) for exact readback. Promoted MP4 records include verifiedMedia with the verified container, video codec, audio codec, duration, width, and height for format compatibility checks. Promoted audio records include the verified container, audio codec, bitrate, channel count, duration, and sample rate. They do not expose storage locations or delivery URLs. The first release is scoped to the same authenticated buyer principal and advertiser that finalized the upload; another teammate does not inherit access merely by belonging to the customer. A finalize accepts up to 50 tags of 64 characters each. Images remain capped at 30 MB, WAV and MP3 audio at 50 MB, and MP4 video at 2 GB. Audio is available as an independent Library asset, but not yet as a save_creative source. Use V3 search({kind: "creative_format", filter: {advertiserId, productId}}) before assembly to list canonical format options on the selected product. Pass the exact opaque Product ID returned by marketplace discovery, including its sf2: prefix. Apostra resolves its storefront, inventory source, and seller-local product identity without falling back to a matching raw ID. productId is required to keep the catalogue read bounded. You can narrow the read further with sellerId or formatKind. The result includes a signed opaque id, the exact formatOptionRef, and each declared slot’s identity, required and repeat cardinality, accepted asset kind, and authored constraints. It also identifies the seller by display name and id. The read does not require a campaign or destination and makes no provider call or setup request. Seller-owned product declarations are available without a provider connection; direct-adapter products keep their existing active-connection visibility rules. Use the returned opaque id with get({kind: "creative_format", id, advertiserId}) to read the same declaration again. The read excludes legacy global format catalogue entries. V3 save_creative turns asset-library records into one format-bound Creative. For campaign-independent assembly, send advertiserId, the selected format id as creativeFormatId, and sourceAssets; each source binding supplies assetId and names its required image or video slot. Add mode: "draft" to save a partial advertiser-owned assembly before every required slot is ready. Revise it with the same creativeId, the current stateRevision as expectedRevision, the signed creativeFormatId, and the complete replacement slot state. Use mode: "complete" when the assembly is ready for full format validation. Drafts and completed advertiser assemblies stay outside campaigns and do not contact a provider. Apostra revalidates the signed format and derives its canonical kind and option on every save. Supply copy and destination slots through social and clickUrl. A stale revision fails without changing the Creative, and a replacement never silently merges with its prior state. For a campaign-scoped create, send campaignId, formatKind, and the campaign product’s exact formatOptionRef; that legacy save also attaches the new Creative to the campaign. Calls that omit mode retain complete-save behavior. Apostra rejects expired or foreign assets, stale or mismatched format selections, undeclared slots, wrong media types, duplicate slot values, and missing required slots at completion. The saved result is the Creative manifest. An advertiser-level assembly appears once under All creatives and its authoritative V3 search and readback contain durable asset rows, state, the current numeric stateRevision, and membership.campaignIds. To associate a completed advertiser Creative before a seller package exists, call save_creative with its creativeId, advertiserId, and campaignId only. Repeating that call is safe. The association records campaign membership; it does not assign a package, create provider delivery, or create spend. Those are separate later states. To set the full set of campaigns an advertiser Creative runs on, call save_creative with creativeId, advertiserId, and campaignIds: the list replaces membership, so a campaign missing from it is detached and a new one attached. Omitting campaignIds never detaches. Attaching checks the campaign’s sellers: when the campaign has media buys and no seller’s products accept the Creative’s format, the call fails and names those sellers; a campaign with no media buys yet accepts any complete Creative, while a media buy whose products declare no accepted formats cannot be checked, so the save fails closed. A Creative live on an active or paused media buy cannot be detached until that buy ends. Every way of changing membership, including the Library picker and the singular campaignId association, shares one lock protocol, so concurrent membership writes to the same Creative or campaign do not overlap: a write that finds another one in progress, or whose target set changed while it was being prepared, returns CONFLICT and should be retried with the full set. The same edge is set from the campaign side with save_campaign.creativeIds and from the Creative Library picker; readback is membership.campaignIds on the Creative and creatives on the campaign. The existing opaque revision remains the buyer-preview projection digest. The same completion view can load that exact saved state through Show preview. Creative collections contain assembled Creatives, not the independent uploaded assets. V2 MCP sessions can open the same upload Task, but asset search/get and assetId assembly are V3-only.

Preview a saved Creative

In the Creative Library, select Show preview to run the current saved revision in an isolated frame. The frame uses Apostra’s render origin. It does not embed a provider preview or run the Creative in the Library page. V3 clients can request the same read with get({kind: "creative", id, advertiserId, include: ["preview"]}), or use the Creative’s campaign as sourceId. The preview field contains only renderUrl, expiresAt, the opaque preview revision, and the exact current numeric stateRevision. If the saved format has no first-party renderable asset, it contains a reason instead. Existing get calls omit preview unless it is included, but every Creative read now returns the whole-state stateRevision and no longer forwards the legacy V2 provider preview URL or tracker fields. The buyer preview renders direct image, video, and audio source assets. HTML, VAST, DAAST, and ZIP sources return a not-renderable reason because their nested documents can load provider resources or measurement trackers that are not safe to project into this read. Preview URLs expire after 15 minutes and stop working sooner if the Creative changes. Request a new preview after expiry or whenever the returned revision or stateRevision differs from the Creative read. Storage URLs, provider preview HTML, and measurement trackers are not returned by the V3 Creative read. A VAST url asset also takes vast_version — one of 2.0, 3.0, 4.0, 4.1, 4.2, 4.3. Declare it: a managed ad-server destination checks the version against the ones it holds delivery evidence for, so a tag without one is not eligible for those routes and fails creative sync. See video creatives.

HTML5 bundles

Canonical html5 creatives use one ZIP asset in the html5_bundle slot, with an optional backup_image. Buyer chat inspects these packages without running their JavaScript, preserves the ZIP, and carries the declared dimensions into seller matching. Generic multi-creative ZIPs continue to expand into separate creatives. Direct multipart ZIP creation and reclassification are rejected; use the inspected buyer-chat upload path. An imported bundle is not automatically delivery-ready. Media-buy sync requires an explicit landing-page URL, and compatibility fails closed when a seller declares an HTML5 runtime constraint that inspection cannot verify.

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. Apostra auto-classifies assets, processes HTML to rewrite local references to CDN URLs, inserts ADCP macros, and generates a preview. If the campaign already has non-draft media buys, a complete new manifest is automatically propagated to their active sellers; no separate sync_creatives call is required.

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, Apostra 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. Apostra 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. Apostra 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, Apostra 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. Apostra 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.

Composer drafts

For a campaign, the Creative Library can open a Composer Task without Creative Engines. Choose Snap Story, Meta Reels, Display 300×250, or Audio :30, then fill its copy and uploaded-asset slots, name the draft, add its click-through URL, and save it. The Task shows which slots are filled and a live preview, then saves the assembly draft in the campaign’s Creative Session without selecting or calling an engine. Use the host chat to request changes. The Task does not provide a second change bar and reloads the session after chat updates it. Saving a composer draft keeps work in review; it does not create a campaign Creative, attach it to delivery, or make it live. When Creative Engines is not enabled, the Task keeps assembly controls available and labels generative controls unavailable. Ask your Apostra account team to enable it for the Buyer Account; generation also needs a connected engine and applicable provider setup. 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.

When Apostra generates directions in separate calls and the request includes request.idempotency_key, give each direction a distinct short label. Provider keys use the first 40 characters after lowercasing, replacing characters outside a-z and 0-9 with hyphens, and trimming edge hyphens. Labels such as Summer sale and summer-sale therefore collide. Apostra rejects that batch before calling a generator; change the labels before retrying. Existing keys for unambiguous directions remain unchanged. 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. When refining a variant, send only the request settings you want to change for that refinement. Omitted settings retain the session’s saved values. Nested objects merge; arrays and scalar values replace the supplied field. Explicit null values in config are forwarded to the provider for validation. A string creative_brief replaces the brief used for that refinement. Provider setting overrides do not change the session defaults, and the selected variant remains the parent. If a finalization response is lost, read the session before retrying. Once the session reports finalized, repeating the same selected variant, name, and message returns its saved result without creating another campaign creative. Retries still require current campaign write access. Different inputs return a conflict; use the saved creative_id to read or update the campaign creative. For older finalized sessions that did not retain the original request, retry without name or message overrides. This retry behaviour applies after the finalized session has been saved. It does not guarantee recovery from an interruption between creative creation and session persistence, or from concurrent finalization requests. A session that does not report finalized is not proof that no creative was created.

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, legacy or canonical format identity, 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 identity, 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.

Asset URLs must be publicly fetchable

Every asset URL on a finalized creative manifest is forwarded verbatim to the seller’s ad server, which fetches it from its own infrastructure with no Apostra credentials. So a manifest asset URL has to be a publicly reachable https:// (or http://) URL — those are the only two schemes accepted when you submit one. Apostra-internal storage locations are not deliverable, even though they resolve for you while you are authoring. That includes gs:// object URIs, scope3-<kind>:// internal handles, and https://storage.googleapis.com/... URLs that address an Apostra-managed private bucket. These are refused wherever they appear. Schemes other than http(s): — tel:, market:// and the like — are refused too, both at upload and whenever the creative is rebuilt from its manifest for delivery. A manifest row that already stores one is not re-refused on a path that forwards the stored payload as-is, so an existing deep link keeps working there. Those refusals name the scheme, so you can tell them apart from a storage refusal. The check runs when the creative is projected for delivery, so it can surface on sync_creatives, on media-buy execution, and on a media-buy update that assigns creatives — not only at upload time. If an asset is not deliverable you get a 422 INVALID_REQUEST naming the refused creative:

{
  "error": {
    "code": "INVALID_REQUEST",
    "field": "cr_9f2a",
    "message": "Creative cr_9f2a references storage that cannot be delivered to a destination. Publish the offending asset at a public HTTPS URL and retry."
  }
}

The subject is the creative when the refusal comes from syncing or executing an existing creative, and the individual asset (for example hero-2024) when it comes from building the creative in the first place. If your id contains characters we do not echo back — a dot or a space, say — the message says “A creative on this request…” instead of naming it, and field reads creative. To fix it, publish the asset at a public HTTPS URL you control (or a CDN), then update the manifest asset to point at that URL and retry.

The message deliberately does not say which storage location was detected, and on the sync/execute path it names the creative rather than the individual asset slot. If you cannot tell which asset in a multi-asset manifest was refused, contact support — Apostra retains the exact slot and the specific reason in server-side logs and can tell you which one to fix.

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.apostra.com/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.apostra.com/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",
      "vast_version": "2.0"
    }
  };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.apostra.com/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.apostra.com/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X PUT https://api.apostra.com/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.apostra.com/api/v2/buyer/campaigns/cmp_987654321/creatives/cm_abcdef \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Render an ADCP preview

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

Calls the configured ADCP creative agent or platform adapter’s preview_creative tool. Provider-backed renders are returned as external links and are never executed inline. Availability and fail-closed behavior vary by platform; see Creative preview support.

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/create`	Create a master directly under the advertiser, with no campaign
`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.

Advertiser creative collections

An advertiser can group its saved creatives into named collections that live with the advertiser rather than with a campaign. A collection is non-executable: it holds creatives, it does not deliver them. Attach a collection from a campaign to make its creatives available there. Changes to a collection carry a revision check so concurrent edits fail loudly instead of overwriting each other. In the Creative Library page, creatives and collections show in a grid or a list, switchable from the toolbar, with the same rows, search, and filters in both. See Manage advertiser creative collections.

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, Apostra 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

Apostra resolves identity macros when the creative is synced for a media buy. It fills {MEDIA_BUY_ID}, {CREATIVE_ID}, and {CAMPAIGN_ID} in Apostra tracker URLs and in the click-URL parameters resolved from the advertiser, campaign, and creative layers. In tracker URLs {PACKAGE_ID} resolves to an empty value because one synced creative can be assigned to multiple packages. In click-URL parameters the media-buy value is the storefront transaction id used for attribution; a parameter whose identity macro has no value for that sync is omitted instead of carrying a different id. Serve-time environment macros such as {CACHEBUSTER}, {DEVICE_TYPE}, {COUNTRY}, and consent strings remain literal in the outbound asset for the publisher/ad server to fill when the impression serves. Self-contained HTML is the exception: its embedded Apostra tracker fires directly in the browser, so Apostra injects an HTML-safe URL with no unresolved identity placeholders. The tracking.supported_macros array on the manifest response lists the 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.apostra.com — Apostra’s own measurement domain in production (/agentic/imp for impressions, /agentic/clk for clicks). Because it is Apostra’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, resolved when the creative is synced to the media buy
`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.apostra.com is an Apostra 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.apostra.com 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 selected legacy or canonical format identity. Creating a complete manifest after the campaign already has non-draft media buys also propagates it to their active sellers, without a separate sync_creatives call. The same manifest can serve multiple media buys; later updates re-sync. Use sync_status to confirm publishers have received the latest version. synced is true only when every current sales-agent link succeeded; agent_count counts successful agents, and last_synced_at comes only from successful links. Failed platform links include rejection_reason when the seller supplied one. The Creative Library detail shows the same links as a Seller approval table: a seller’s Rejected or Changes requested verdict stands until it reports a new one; otherwise a row reads Sync failed when the current version could not be delivered, Approved once the seller approved a delivered version, and Reviewing until then. The seller’s note appears only under a rejected or changes-requested row. When a Creative has a click URL, its collapsed Destination section shows the authored URL, the delivered URL after effective additions, and whether each addition came from the advertiser, campaign, or Creative.

Creative transport modes

Apostra 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), Apostra falls back to the seller’s advertised tools and uses sync_creatives when available. During initial media-buy execution, Apostra reuses creatives that have current-revision evidence in the same seller account’s library. Those creatives remain creative_assignments on retries instead of being re-sent as inline creates. If sync_creatives fails for the remaining new creatives and the seller allows inline creatives, only those unsynced creatives fall back inline during execution; existing library creatives remain assignments. Media-buy updates retain the seller-wide inline fallback when sync fails. If the seller is library-only and a required new creative fails to sync, the 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

​Uploaded assets and assembled Creatives

​Browse an advertiser’s Creative Library

​Preview a saved Creative

​HTML5 bundles

​Lifecycle

​Media-buy compatibility results

​Conversational creative sessions

​Composer drafts

​Required placement shapes

​Asset lifecycle

​Asset URLs must be publicly fetchable

​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

​Advertiser creative collections

​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

Uploaded assets and assembled Creatives

Browse an advertiser’s Creative Library

Preview a saved Creative

HTML5 bundles

Lifecycle

Media-buy compatibility results

Conversational creative sessions

Composer drafts

Required placement shapes

Asset lifecycle

Asset URLs must be publicly fetchable

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

Advertiser creative collections

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