feat: filter list_creatives by creative asset type

[bokelley]

Problem

AdCP has a canonical PublishedPostAsset and canonical format params for
publisher-owned references, but list_creatives cannot filter creative rows by
asset type.

A cross-platform buyer wanting to show “existing published posts” must currently
fetch creative rows and inspect assets.published_post locally. Filtering by
format_ids is not a valid substitute: that field carries legacy
{agent_url, id} format identity, while published-post rows may be canonical
format_kind + format_option_ref. Requiring every buyer to download unrelated
creative rows is inefficient and duplicates protocol semantics in each host.

Proposal

Add an optional asset-type filter to CreativeFilters, reusing the existing
AssetContentType vocabulary:

{
  "filters": {
    "asset_types": ["published_post"]
  }
}

Recommended semantics: a creative matches when it contains at least one asset
whose asset_type is in the requested set. Multiple requested values are OR,
consistent with format_ids and statuses. The field should be exact and
conjunctive with other filters.

Why this belongs in AdCP

published_post is already a cross-platform protocol asset. Buyers and shared
MCP Apps should be able to request that creative flavor without knowing
publisher-specific format options or inventing an extension. The same filter is
useful for image/video/audio/VAST creative libraries.

Acceptance

• Schema and generated SDK types expose
  CreativeFilters.asset_types?: AssetContentType[].
• list_creatives documentation defines OR-within-field and AND-across-fields
  semantics.
• Conformance fixtures cover published_post, mixed-asset creatives, empty
  results, and interaction with format_ids.
• No agent_url or platform-specific post fields are introduced.

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol, creative
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Conditional-approve — vocabulary fit is sound; AssetContentType should gain zip before the field ships, and the field description needs a normative seller fallback clause for agents that don't implement the filter.
• adtech-product-expert: Conditional-approve — use case is real (boosted-post workflows, cross-platform creative discovery); spec must define traversal depth into creative.assets and flag that url/text/image are near-universal types that make poor standalone filter values.

My take: The pattern is already proven — list_creative_formats carries an identical asset_types filter using AssetContentType (with a published_post callout in its description). Extending it to the creative library is a natural, non-breaking minor addition. Three spec precision points need WG resolution before implementation; the decision memo below captures them for ratification.

---

Decision Memo — Normative (pending WG ratification)

class: normative
status: recorded
date: 2026-07-29
refs: ["#6089"]
dissent: none

Ruling: Add asset_types?: AssetContentType[] to CreativeFilters (static/schemas/source/core/creative-filters.json). A creative matches when at least one slot in its creative.assets map carries an asset_type value in the requested set. OR within the field; conjunctive (AND) across other filter fields — consistent with statuses, format_ids, and concept_ids.

Rationale: list_creative_formats already carries this exact filter under the same name and vocabulary (/schemas/enums/asset-content-type.json), enabling buyers to discover format specs that require a given content type. The creative library has no equivalent. Cross-platform buyers managing boosted-post campaigns must today enumerate publisher-specific format IDs (meta_existing_post, TikTok Spark, Snap Promoted Stories, etc.) to locate published-post creatives, coupling a protocol-level creative-source choice to every platform's local format catalog. published_post is already a first-class protocol asset; a filter on it is the natural complement and eliminates a known integration footgun.

Three open questions for WG resolution:

1. Vocabulary gap: AssetContentType currently lacks zip (HTML5 bundle creatives). zip is a meaningful buyer discovery target (buyers looking for HTML5 banner creatives have no way to express that filter under the current enum). Recommend adding zip to AssetContentType as a companion change. vast_tracker, daast_tracker, pixel_tracker, and card are ancillary/structural types — not buyer discovery targets — and should remain excluded.

2. Seller fallback contract: The field description MUST state what a seller does when it does not implement this filter. Recommended: treat the field as absent and return all results from remaining active filter criteria (over-returning, not rejecting). Parallel to the role-boundary annotations on assigned_to_packages and unassigned in the same schema.

3. Traversal depth: "Creative contains an asset of type X" must be precisely defined. Recommend: match top-level creative.assets slots only for v1 (covers all primary-payload use cases including published_post; recursion into array-typed slots such as carousel cards[] items is a scoped follow-up).

Implications: Non-breaking minor; targets main (next 3.2 minor), not a 3.1.x patch (stable-schemas patch rule). Acceptance criteria from the issue are sound. Conformance fixtures should additionally cover: mixed-asset creatives with both matching and non-matching slots, interaction with format_ids, and the near-universal-type cases (url, text, image) with documentation warning.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01V98y9ytHEsjzGQs4FNRBY6

---

Generated by Claude Code