list_collections

​

When to use it

​

Request

{
  "$schema": "/schemas/3.3.0-beta.0/latest/media-buy/list-collections-request.json",
  "adcp_version": "3.3",
  "collections": [
    { "publisher_domain": "novacreators.example", "collection_ids": ["kitchen_lab"] },
    { "publisher_domain": "pinnaclepods.example", "collection_ids": ["founders_hour"] }
  ]
}

{
  "$schema": "/schemas/3.3.0-beta.0/latest/media-buy/list-collections-request.json",
  "adcp_version": "3.3",
  "account": { "account_id": "acct_nova_agency" },
  "filters": {
    "kinds": ["series"],
    "statuses": ["active"],
    "languages": ["en"],
    "talent": [{ "domain": "jordanvega.example" }],
    "platforms": ["videoplatform.example"]
  },
  "pagination": { "max_results": 50 }
}

​

Response

{
  "$schema": "/schemas/3.3.0-beta.0/latest/media-buy/list-collections-response.json",
  "outcome": "listed",
  "collections": [
    {
      "publisher_domain": "novacreators.example",
      "collection_id": "kitchen_lab",
      "name": "Kitchen Lab with Jordan Vega",
      "kind": "series",
      "status": "active",
      "language": "en",
      "cadence": "weekly",
      "description": "Weekly food science experiments for home cooks",
      "url": "https://novacreators.example/creators/kitchen-lab",
      "images": [
        {
          "asset_type": "image",
          "url": "https://cdn.novacreators.example/kitchen-lab/avatar.jpg",
          "width": 800,
          "height": 800,
          "alt_text": "Kitchen Lab channel avatar"
        }
      ],
      "talent": [
        { "role": "creator", "name": "Jordan Vega", "brand_ref": { "domain": "jordanvega.example" } }
      ],
      "distribution": [
        {
          "publisher_domain": "videoplatform.example",
          "identifiers": [{ "type": "youtube_channel_id", "value": "UCexample123456" }],
          "followers": {
            "lower_bound": 1230000,
            "upper_bound": 1239999,
            "precision": "approximate",
            "as_of": "2026-10-15T00:00:00Z"
          }
        }
      ]
    }
  ],
  "pagination": { "has_more": true, "cursor": "eyJvIjo1MH0=" },
  "collections_version": "cc_2026_10_16_r88",
  "cache_scope": "account"
}

• One entry per key. A response has at most one entry per (publisher_domain, collection_id). If a key appears more than once, that collection is unresolvable from the response and the buyer falls back to adagents.json, the same duplicate rule as for include_collections.
• Silent omission. A selector key that is unknown, or not visible to the caller, is omitted with no per-key error. “Doesn’t exist” and “not yours” look the same, as with the uniform response rule behind REFERENCE_NOT_FOUND. Buyers detect omissions by comparing their selectors with the returned entries, as they already do for include_collections.
• What is returned. The seller returns only collections it represents and can sell to the caller, meaning collections that its products offered to that caller can reference. Ended and upcoming collections are allowed, with their status. It SHOULD return only collections whose publisher’s adagents.json authorizes it, directly or through a collection-scoped selector. Card fields are public display data: the response carries no pricing, availability or account terms.

​

Authority

​

Versioning and caching

{
  "$schema": "/schemas/3.3.0-beta.0/latest/media-buy/list-collections-request.json",
  "adcp_version": "3.3",
  "account": { "account_id": "acct_nova_agency" },
  "filters": {
    "kinds": ["series"],
    "statuses": ["active"],
    "languages": ["en"],
    "talent": [{ "domain": "jordanvega.example" }],
    "platforms": ["videoplatform.example"]
  },
  "if_collections_version": "cc_2026_10_16_r88"
}

{
  "$schema": "/schemas/3.3.0-beta.0/latest/media-buy/list-collections-response.json",
  "outcome": "unchanged",
  "collections_version": "cc_2026_10_16_r88",
  "cache_scope": "account"
}

• Scope. The version is scoped to the agent, the canonicalized collections selectors and the canonicalized filters, plus account identity when cache_scope is account. Arrays have set semantics. pagination.cursor is outside the scope. A token presented with different selectors or filters is a mismatch and gets a full listed response.
• What moves it. The version changes when any copy the selection would return changes, or when the set of collections it selects changes. A follower refresh that leaves a count’s lower_bound, upper_bound and precision unchanged is not a change: it moves no version and keeps the earlier as_of (see follower counts).
• Pages. If a later page arrives with a different collections_version, the catalog changed mid-walk: restart from the first page, as with wholesale feed versioning.
• Independent of product feeds. collections_version is not the include_collections scope of feed_version or wholesale_feed_version. A change to one says nothing about the others, so card churn never forces a product mirror to refetch.
• cache_scope. A request without account gets public. A request with account gets public or account, as the seller declares, with the same downgrade semantics as wholesale feeds: a later public on a conditional request that was account means the account no longer has its own visible set. Only the set of visible collections may vary by account. The content of a copy for a given key never does: there is one card per collection per seller.

​

Collection card webhooks

​

Registration

{
  "$schema": "/schemas/3.3.0-beta.0/latest/account/sync-accounts-request.json",
  "idempotency_key": "9b1e6f2c-4d8a-4c51-9f0e-3a7d2c8b6e41",
  "accounts": [
    {
      "account": { "account_id": "acct_nova_agency" },
      "notification_configs": [
        {
          "subscriber_id": "card-mirror",
          "url": "https://buyer.example/hooks/collection-cards",
          "event_types": [
            "collection_card.updated",
            "collection_card.removed",
            "collection_catalog.bulk_change"
          ],
          "active": true
        }
      ]
    }
  ]
}

​

Events

​

Envelope

• notification_id equals event.event_id, and notification_type equals event.event_type.
• account_id is required, and cache_scope equals event.payload.applies_to.scope.
• product_payload_view is omitted.
• wholesale_feed_version carries the post-change collections_version of the unfiltered catalog, the same way the list_products feed_version travels in that field.
• event.entity_type is collection for card events and feed for the bulk event. entity_id is opaque: receivers key the mirror on the payload’s (publisher_domain, collection_id), never on entity_id.
• Delivery follows the persistent webhook contract unchanged: at least once, deduped on idempotency_key, no ordering guarantee, and RFC 9421 signing (webhook_signing.supported is true once wholesale_feed_webhooks.supported is).

{
  "$schema": "/schemas/3.3.0-beta.0/latest/core/wholesale-feed-webhook.json",
  "idempotency_key": "whk_01JAC2N4S8J4TK8M6D3K9Q2P1A7",
  "notification_id": "0192a6f0-0000-7000-8000-000000000101",
  "notification_type": "collection_card.updated",
  "fired_at": "2026-10-17T14:00:02Z",
  "subscriber_id": "card-mirror",
  "account_id": "acct_nova_agency",
  "wholesale_feed_version": "cc_2026_10_17_r89",
  "previous_wholesale_feed_version": "cc_2026_10_16_r88",
  "cache_scope": "public",
  "event": {
    "event_id": "0192a6f0-0000-7000-8000-000000000101",
    "event_type": "collection_card.updated",
    "entity_type": "collection",
    "entity_id": "card_7f3a91",
    "created_at": "2026-10-17T14:00:00Z",
    "payload": {
      "collection": {
        "publisher_domain": "novacreators.example",
        "collection_id": "kitchen_lab",
        "name": "Kitchen Lab with Jordan Vega",
        "kind": "series",
        "status": "active",
        "url": "https://novacreators.example/creators/kitchen-lab",
        "sample_content": [
          {
            "asset_type": "published_post",
            "post_url": "https://videoplatform.example/watch/kl-0143",
            "platform": "videoplatform.example",
            "published_at": "2026-10-16T15:00:00Z"
          }
        ]
      },
      "changed_fields": ["sample_content"],
      "applies_to": { "scope": "public" }
    }
  }
}

​

Volume

• Per-card collection_card.updated is for an editorial change to one card (a new thumbnail, a new sample, a description or season edit, a status change) and for one card entering the catalog. collection_card.removed is for one card leaving it.
• A seller SHOULD send one collection_catalog.bulk_change instead of per-card events when one operation touches more than 5% of the catalog or more than 100 cards, whichever is smaller. This is the wholesale feed threshold. A scheduled sweep that refreshes follower counts is the typical case and SHOULD always go out as one bulk event, never as a stream of per-card events.
• A refresh that leaves a count’s bounds and precision unchanged is not a card change: it fires nothing and produces no new version, and the earlier as_of stays.

​

Versions and repair

1. Bootstrap from an unfiltered list_collections read (no selectors, no filters) of every page, and store collections_version and cache_scope. Webhook versions describe the unfiltered catalog for their cache_scope, so tokens from filtered reads cannot be compared with them.
2. Apply each event, then store the event’s version.
3. On a gap (previous_wholesale_feed_version doesn’t match the stored version), a failed signature, or a stale version, repair with list_collections and if_collections_version set to the last applied version. The webhook’s version is never the conditional token for a stale mirror.
4. On collection_catalog.bulk_change, or any uncertain state, drop the token and replace the mirror from a complete unfiltered read.

​

Authority, scope and privacy

• A pushed card is a response copy, and the authority rules apply unchanged. collection_card.removed means only that this seller stopped offering the card. It does not mean the collection was retired or that authorization changed; those facts arrive as registry collection.removed and authorization.revoked.
• A buyer recomputes its merged view when either feed fires. A card event changes closed-list fields, a registry event changes anchored fields, and neither overrides the other’s fields.
• applies_to is required on every event. Because copy content does not vary by account, account-scoped events only move a card into or out of an account’s visible set, and content changes to a public card are public events.
• Sellers MUST apply the list_collections visibility predicate when they emit. A subscriber whose account cannot see a card through list_collections MUST NOT receive its events.

​

Capability and version gate

• Feature id. media_buy.collection_catalog covers list_collections, its request and response schemas, and the three webhook event types. A seller that lists it MUST also list media_buy.collection_cards. A seller can serve cards in-band through include_collections without running this read, and the two surfaces can graduate separately.
• Discovery. The task is not in media_buy.lifecycle_tools, which lists the product and MediaBuy lifecycle. Buyers see the feature id, and the tool in tools/list or the A2A skills.
• Webhooks are optional within the feature. A seller can declare the read without push. Listing any collection_card.* event or collection_catalog.bulk_change in wholesale_feed_webhooks.event_types requires listing media_buy.collection_catalog, because list_collections is the repair path.
• Version gate. list_collections is a 3.3 task. A seller MUST NOT serve it to a caller whose adcp_version is below 3.3, and fails such a request with UNSUPPORTED_FEATURE.

​

Conformance