AdCP — Property List Management

Tasks: Create, update, get, list, and delete property lists. Property lists are managed resources that combine static property sets with dynamic filters. When resolved, filters are applied to produce the final property set.

Architecture: Setup Time, Not Real-Time

Property lists are designed for setup-time operations, not real-time bid decisions:

┌─────────────────────────────────────────────────────────────────┐
│                     SETUP TIME (Campaign Planning)              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Buyer creates/updates property list on governance agent     │
│  2. Buyer resolves list to get current properties               │
│  3. Buyer provides list_id to orchestrator/seller               │
│  4. Orchestrator/seller fetches and caches resolved list        │
│  5. Campaign targets only cached compliant properties           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     BID TIME (Milliseconds)                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  • Orchestrator/seller uses LOCAL cache only                    │
│  • NO calls to governance agent                                 │
│  • Pass/fail from cached property set                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     REFRESH (Periodic)                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  • Orchestrator/seller re-fetches list on schedule              │
│  • Frequency based on cache_valid_until                         │
│  • Typically every 1-24 hours                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

This enables:

Static lists: Curated sets of approved properties
Dynamic lists: Properties matching criteria (country, channel, score thresholds)
Hybrid lists: Base set modified by filters

Tasks Overview

Task	Purpose	Response Time
`create_property_list`	Create a new property list	~500ms
`update_property_list`	Modify an existing list	~500ms
`get_property_list`	Retrieve list with resolved properties	~2-5s (depending on size)
`list_property_lists`	List all property lists	~500ms
`delete_property_list`	Delete a property list	~200ms

Property List Structure

A property list contains:

{
  "list_id": "uk_premium_news_q1",
  "name": "UK Premium News Sites Q1 2026",
  "description": "High-quality UK news sites for Q1 campaign",
  "account": { "account_id": "acc_brand_x_direct_01" },
  "base_properties": [
    {
      "selection_type": "publisher_tags",
      "publisher_domain": "raptive.com",
      "tags": ["premium_news", "uk_tier1"]
    }
  ],
  "filters": {
    "countries_all": ["UK"],
    "channels_any": ["display", "video"],
    "feature_requirements": [
      { "feature_id": "mfa_score", "min_value": 90, "max_value": 100 }
    ]
  },
  "brand": {
    "domain": "acmecorp.com"
  },
  "created_at": "2026-01-03T10:00:00Z",
  "updated_at": "2026-01-03T10:00:00Z",
  "property_count": 847
}

Domain identifier format

For domain and subdomain identifiers, value MUST be a lowercase ASCII hostname with at least two labels. Internationalized names MUST use lowercase IDNA A-label (punycode) form. Each label has 1–63 letters, digits, or hyphens, starts and ends with a letter or digit, and labels are separated by dots. The hostname is at most 253 characters, excluding an optional wildcard prefix. Schemes, paths, query strings, fragments, ports, whitespace, underscores, and trailing dots are invalid. These constraints are enforced by core/identifier.json.

Type	Valid examples	Matching
`domain`	`example.com`, `edition.example.com`, `*.example.com`	A base domain matches itself plus its `www` and `m` variants; a named subdomain matches that subdomain; a leading `*.` matches all subdomains, excluding the base.
`subdomain`	`edition.example.com`	Matches the exact hostname. Wildcards are invalid.

The optional *. is permitted only once, at the start of a domain value. It is a matching selector, not part of the hostname. The format check does not perform DNS resolution or establish ownership. Reserved test hostnames such as publisher.example are valid protocol identifiers; the public registry applies additional contribution restrictions. A receiver MUST reject a create, update, or other request containing an invalid identifier with INVALID_REQUEST, identifying the offending field. It MUST NOT silently skip or reinterpret the value. A sender MAY offer explicit URL-to-hostname conversion before submission, but MUST validate the resulting identifier. This applies to inclusion lists, exclusion lists, and filters.exclude_identifiers. If an invalid identifier arrives in a fetched list, the receiver MUST reject that snapshot and report the failure to its caller; it MUST NOT apply a partial list.

Brand

Instead of manually specifying all filters, provide a brand reference and let the governance agent apply appropriate rules based on who you are:

{
  "brand": {
    "domain": "toybrand.com"
  }
}

The agent resolves the brand identity and applies rules based on its domain expertise:

A consent agent applies COPPA requirements based on the brand’s target audience
A brand safety agent infers content categories from the brand’s industry
A sustainability agent applies requirements from the brand’s profile

The brand reference uses the standard core/brand-ref schema. The governance agent resolves the domain to discover the brand’s identity via its brand.json file.

Webhooks

Configure webhooks via update_property_list to receive notifications when the resolved list changes. Important: Webhooks provide notification only. They tell you that the list has changed, but do not stream the updated properties. After receiving a webhook, you must call get_property_list to retrieve the updated property set.

Webhook Flow

Governance agent re-evaluates properties (periodically or on trigger)
Agent detects changes to the resolved property list
Webhook fires with change summary (counts, not full list)
Recipient calls get_property_list(list_id, resolve=true)
Recipient updates local cache with new properties

Webhook Payload

{
  "idempotency_key": "plch_01HW9DFQK6NP9R3T5V7X9Z1B3D",
  "event": "property_list_changed",
  "list_id": "uk_premium_news_q1",
  "list_name": "UK Premium News Sites Q1 2026",
  "change_summary": {
    "properties_added": 12,
    "properties_removed": 3,
    "total_properties": 856
  },
  "resolved_at": "2026-01-03T18:00:00Z",
  "cache_valid_until": "2026-01-04T18:00:00Z",
  "signature": "rfc9421"
}

The webhook payload includes counts but NOT the actual properties. This keeps payloads small and avoids redundant data transfer when recipients may not need the full list immediately. Recipients MUST verify the delivery’s RFC 9421 Signature, Signature-Input, and Content-Digest HTTP headers before processing, following the webhook profile. The required body-level signature: "rfc9421" is a deprecated compatibility marker retained through 3.x; receivers MUST ignore it for authentication. Recipients MUST also dedupe by idempotency_key so retried deliveries of the same change event are ignored.

Webhook Use Cases

Buyer agent aggregation: Receive updates from multiple specialized agents, intersect results
Seller cache invalidation: Know when to re-fetch the compliant property list
Alerting: Notify when significant changes occur to compliance status

Filters

Filters are applied when the list is resolved (via get_property_list):

Filter	Type	Description
`countries_all`	string[]	ISO 3166-1 alpha-2 country codes (case-insensitive, uppercase recommended) - property must have feature data for ALL. Optional — omit for global lists.
`channels_any`	string[]	Advertising channels - property must support ANY. Optional — omit for all-channel lists.
`property_types`	string[]	Property types (website, mobile_app, ctv_app, etc.)
`feature_requirements`	FeatureRequirement[]	Requirements based on agent-provided features
`exclude_identifiers`	Identifier[]	Identifiers to always exclude

Feature Requirements

Feature requirements reference features discovered via get_adcp_capabilities. Each agent exposes different features (mfa_score, carbon_score, coppa_certified, etc.). For quantitative features (scores, ranges):

{ "feature_id": "mfa_score", "min_value": 85, "max_value": 100 }

For binary features (true/false):

{ "feature_id": "coppa_certified", "allowed_values": [true] }

For categorical features (enum values):

{ "feature_id": "content_category", "allowed_values": ["news", "sports", "technology"] }

Handling Missing Coverage

When a property doesn’t have data for a required feature, you can control the behavior with if_not_covered:

{
  "feature_id": "mfa_score",
  "min_value": 70,
  "if_not_covered": "include"
}

Value	Behavior	Use Case
`exclude` (default)	Property is removed from the list	Strict enforcement - only include properties with verified data
`include`	Property passes this requirement	Lenient enforcement - don’t penalize for coverage gaps

When if_not_covered: "include" is used, the response includes a coverage_gaps field showing which properties were included despite missing data:

{
  "identifiers": [...],
  "coverage_gaps": {
    "mfa_score": [
      { "type": "domain", "value": "app.example.com" },
      { "type": "domain", "value": "ctv.example.com" }
    ]
  }
}

This transparency helps agencies distinguish between properties that passed a requirement vs. those that couldn’t be evaluated.

Required Filters

Every property list must include at least:

One country in countries_all (ISO 3166-1 alpha-2 code, case-insensitive)
One channel in channels_any (display, video, audio, etc.)

These are required because governance agents need to know which jurisdiction and context to evaluate properties against.

Filter Logic

The filter field names make the logic explicit:

countries_all: Property must have feature data for ALL listed countries.
channels_any: Property must support ANY of the listed channels.
feature_requirements: Property must pass ALL requirements (AND).

Base Properties

base_properties is an array of property sources to evaluate. Each entry is a discriminated union with selection_type as the discriminator:

{
  "base_properties": [
    {
      "selection_type": "publisher_tags",
      "publisher_domain": "raptive.com",
      "tags": ["premium_news", "tier1"]
    },
    {
      "selection_type": "publisher_tags",
      "publisher_domain": "mediavine.com",
      "tags": ["lifestyle"]
    },
    {
      "selection_type": "identifiers",
      "identifiers": [
        { "type": "domain", "value": "bbc.co.uk" },
        { "type": "domain", "value": "ft.com" }
      ]
    }
  ]
}

Each entry must include selection_type:

selection_type	Required Fields	Description
`publisher_tags`	`publisher_domain`, `tags`	All properties matching these tags within the publisher
`publisher_ids`	`publisher_domain`, `property_ids`	Specific property IDs within the publisher
`identifiers`	`identifiers`	Direct domain/app identifiers (no publisher context)

If base_properties is omitted, the agent queries its entire property database for properties matching the filters. See the base-property-source schema for the full specification.

create_property_list

Create a new property list.

Request

{
  "tool": "create_property_list",
  "arguments": {
    "name": "UK Premium News Q1",
    "description": "High-quality UK news sites for Q1 campaign",
    "base_properties": [
      {
        "selection_type": "publisher_tags",
        "publisher_domain": "raptive.com",
        "tags": ["premium_news"]
      }
    ],
    "filters": {
      "countries_all": ["UK"],
      "channels_any": ["display", "video"],
      "feature_requirements": [
        { "feature_id": "mfa_score", "min_value": 85, "max_value": 100 }
      ]
    }
  }
}

Response

{
  "message": "Created property list 'UK Premium News Q1'.",
  "context_id": "ctx-gov-list-123",
  "list": {
    "list_id": "pl_abc123",
    "name": "UK Premium News Q1",
    "description": "High-quality UK news sites for Q1 campaign",
    "account": { "account_id": "acc_brand_x_direct_01" },
    "base_properties": [
      {
        "selection_type": "publisher_tags",
        "publisher_domain": "raptive.com",
        "tags": ["premium_news"]
      }
    ],
    "filters": {
      "countries_all": ["UK"],
      "channels_any": ["display", "video"],
      "feature_requirements": [
        { "feature_id": "mfa_score", "min_value": 85, "max_value": 100 }
      ]
    },
    "created_at": "2026-01-03T16:30:00Z",
    "updated_at": "2026-01-03T16:30:00Z",
    "property_count": 847
  },
  "auth_token": "eyJhbGciOiJIUzI1NiIs..."
}

Dynamic List (Filters Only)

Create a list that dynamically queries the governance agent’s database (no base_properties - uses agent’s full coverage):

{
  "tool": "create_property_list",
  "arguments": {
    "name": "GDPR-Compliant DE Video",
    "description": "All DE properties supporting video with strong consent",
    "filters": {
      "countries_all": ["DE"],
      "channels_any": ["video"],
      "feature_requirements": [
        { "feature_id": "mfa_score", "min_value": 90, "max_value": 100 }
      ]
    }
  }
}

update_property_list

Modify an existing property list.

Request - Update Filters

{
  "tool": "update_property_list",
  "arguments": {
    "list_id": "pl_abc123",
    "filters": {
      "countries_all": ["UK"],
      "channels_any": ["display", "video"],
      "feature_requirements": [
        { "feature_id": "mfa_score", "min_value": 80, "max_value": 100 }
      ]
    }
  }
}

Request - Replace Base Properties

{
  "tool": "update_property_list",
  "arguments": {
    "list_id": "pl_abc123",
    "base_properties": [
      {
        "selection_type": "publisher_tags",
        "publisher_domain": "raptive.com",
        "tags": ["premium_news", "uk_tier1"]
      }
    ]
  }
}

Request - Add Exclusions

{
  "tool": "update_property_list",
  "arguments": {
    "list_id": "pl_abc123",
    "filters": {
      "exclude_identifiers": [
        { "type": "domain", "value": "excluded-site.com" }
      ]
    }
  }
}

Response

{
  "message": "Updated property list 'UK Premium News Q1'.",
  "context_id": "ctx-gov-list-456",
  "list": {
    "list_id": "pl_abc123",
    "name": "UK Premium News Q1",
    "updated_at": "2026-01-03T17:00:00Z",
    "property_count": 845
  }
}

get_property_list

Retrieve a property list with optional resolution of filters.

Resolving a property list reference

A receiver given a PropertyListReference MUST invoke get_property_list on the managing agent at agent_url, with list_id from the reference and resolve: true (or its default). The issuer MUST expose this task over MCP at agent_url, and receivers MUST support MCP resolution. Another AdCP task transport advertised by the managing agent, such as A2A, MAY be used by agreement using that transport’s normal task envelope. Implementations MAY also offer custom HTTP download routes, but those are extensions: serving only GET {agent_url}/lists/{list_id} does not satisfy this contract, and receivers MUST NOT infer that path from a reference. When auth_token is present, the receiver MUST send it as Authorization: Bearer <auth_token> on the task transport, including session initialization and every paginated fetch. The managing agent MUST accept this credential in place of its normal authentication. A recipient does not need an existing account or a second credential. The token MUST authorize read-only get_property_list access to that list_id and its continuation pages; it MUST NOT authorize other lists, list enumeration, or mutations. The issuer MUST make the reference unambiguous without requiring an account argument that the reference does not carry. An omitted token requires a public list or independent authorization already available to the receiver. The sender delivers auth_token inside the PropertyListReference passed to the intended receiver, including when that reference is a seller task argument. When authenticating get_property_list requests, receivers MUST send the token only in the Authorization header to the managing agent; it MUST NOT appear in those task arguments, URL paths, query strings, or logs. Receivers MUST NOT forward the credential to another origin on redirect. An expired, revoked, or invalid token is an authorization failure, not an empty list. The receiver MUST report resolution failure to its caller and MUST NOT silently remove the associated targeting constraint. The receiver MUST follow pagination.cursor while pagination.has_more is true, passing the same list_id, resolve, and credential on each request. It MUST validate every page and assemble the complete list before replacing its cached snapshot. An incomplete fetch or invalid page MUST NOT become an active partial inclusion or exclusion list. Refresh the complete snapshot after cache_valid_until or a change notification.

Request - Get Resolved Properties

{
  "tool": "get_property_list",
  "arguments": {
    "list_id": "pl_abc123",
    "resolve": true,
    "pagination": {
      "max_results": 1000
    }
  }
}

Response

The response returns a compact list of identifiers only (not full property objects) for efficiency. Only identifiers that pass the feature requirements are included - no scores or metadata.

{
  "message": "Retrieved property list 'UK Premium News Q1' with 847 resolved identifiers.",
  "context_id": "ctx-gov-list-789",
  "list_id": "pl_abc123",
  "identifiers": [
    { "type": "domain", "value": "bbc.co.uk" },
    { "type": "domain", "value": "news.sky.com" },
    { "type": "domain", "value": "ft.com" },
    { "type": "domain", "value": "theguardian.com" }
  ],
  "pagination": {
    "has_more": true,
    "cursor": "eyJvZmZzZXQiOjEwMH0=",
    "total_count": 847
  },
  "resolved_at": "2026-01-03T17:15:00Z",
  "cache_valid_until": "2026-01-04T17:15:00Z"
}

The auth_token is only returned when the list is created via create_property_list. Store it securely - you’ll need it to share access with sellers.

Request - Get Metadata Only

{
  "tool": "get_property_list",
  "arguments": {
    "list_id": "pl_abc123",
    "resolve": false
  }
}

Response (Metadata Only)

{
  "message": "Retrieved property list 'UK Premium News Q1' metadata.",
  "context_id": "ctx-gov-list-790",
  "list": {
    "list_id": "pl_abc123",
    "name": "UK Premium News Q1",
    "description": "High-quality UK news sites for Q1 campaign",
    "base_properties": [
      {
        "selection_type": "publisher_tags",
        "publisher_domain": "raptive.com",
        "tags": ["premium_news"]
      }
    ],
    "filters": {
      "countries_all": ["UK"],
      "channels_any": ["display", "video"],
      "feature_requirements": [
        { "feature_id": "mfa_score", "min_value": 85, "max_value": 100 }
      ]
    },
    "created_at": "2026-01-03T16:30:00Z",
    "updated_at": "2026-01-03T17:00:00Z",
    "property_count": 847
  }
}

list_property_lists

List property lists owned by a given account, or all property lists accessible to the authenticated agent when account is omitted.

Request

{
  "tool": "list_property_lists",
  "arguments": {
    "name_contains": "UK",
    "pagination": {
      "max_results": 50
    }
  }
}

Response

{
  "message": "Found 3 property lists matching 'UK'.",
  "context_id": "ctx-gov-list-list-123",
  "lists": [
    {
      "list_id": "pl_abc123",
      "name": "UK Premium News Q1",
      "description": "High-quality UK news sites for Q1 campaign",
      "created_at": "2026-01-03T16:30:00Z",
      "updated_at": "2026-01-03T17:00:00Z",
      "property_count": 847
    },
    {
      "list_id": "pl_def456",
      "name": "UK Sports Sites",
      "description": "UK sports content for sponsorship",
      "created_at": "2026-01-02T10:00:00Z",
      "updated_at": "2026-01-02T10:00:00Z",
      "property_count": 156
    }
  ],
  "pagination": {
    "has_more": false,
    "total_count": 3
  }
}

delete_property_list

Delete a property list.

Request

{
  "tool": "delete_property_list",
  "arguments": {
    "list_id": "pl_abc123"
  }
}

Response

{
  "message": "Deleted property list 'UK Premium News Q1'.",
  "context_id": "ctx-gov-list-del-123",
  "deleted": true,
  "list_id": "pl_abc123"
}

Integration with Other Tasks

Using Lists in score_properties

Reference a property list instead of passing properties inline:

{
  "tool": "score_properties",
  "arguments": {
    "property_list_ref": {
      "agent_url": "https://governance.example.com",
      "list_id": "pl_abc123"
    },
    "scoring_context": {
      "jurisdiction": "GDPR"
    }
  }
}

Using Lists in Media Buys

Pass property lists to media buy creation:

{
  "tool": "create_media_buy",
  "arguments": {
    "packages": [{
      "property_list_ref": {
        "agent_url": "https://governance.example.com",
        "list_id": "pl_abc123"
      }
    }]
  }
}

Error Codes

Code	Description
`REFERENCE_NOT_FOUND`	Property list ID doesn’t exist, or the caller lacks access. Returned uniformly for both cases — see Uniform response for inaccessible references. Sellers MUST NOT distinguish “exists but unauthorized” from “does not exist.”
`VALIDATION_ERROR`	Filter configuration is invalid, or a list with the requested name already exists. Correct the filter values or choose a unique name.

Caching and Refresh

The get_property_list response includes caching guidance. When it supplies resolved_at, sellers copy that timestamp into product list_applications receipts; otherwise the seller timestamps completion of its full snapshot fetch, including all pages:

Field	Description
`resolved_at`	When filters were applied and properties resolved
`cache_valid_until`	When consumers should re-fetch the list

Typical flow for orchestrators/sellers:

# Initial setup
response = governance_agent.get_property_list(list_id, resolve=True)
local_cache = build_property_lookup(response.properties)
cache_expiry = response.cache_valid_until

# Periodic refresh (background job)
if now() >= cache_expiry:
    response = governance_agent.get_property_list(list_id, resolve=True)
    local_cache = build_property_lookup(response.properties)
    cache_expiry = response.cache_valid_until

# Bid time (no external calls)
def should_bid(property_domain):
    return property_domain in local_cache

Usage Notes

Setup time only: Governance agents are not in the real-time bid path; resolve lists during campaign setup
Local caching: Orchestrators/sellers must cache resolved properties locally for bid-time decisions
Refresh on schedule: Re-fetch lists based on cache_valid_until (typically every 1-24 hours)
Dynamic vs Static: Use filters-only lists when you want the agent to maintain the property set; use base_properties when you need explicit control
Pagination: Large lists may require multiple requests with cursor-based pagination
No score leakage: Raw scores are kept internal to governance agents; responses contain pass/fail lists, not scores

​Architecture: Setup Time, Not Real-Time

​Tasks Overview

​Property List Structure

​Domain identifier format

​Brand

​Webhooks

​Webhook Flow

​Webhook Payload

​Webhook Use Cases

​Filters

​Feature Requirements

​Handling Missing Coverage

​Required Filters

​Filter Logic

​Base Properties

​create_property_list

​Request

​Response

​Dynamic List (Filters Only)

​update_property_list

​Request - Update Filters

​Request - Replace Base Properties

​Request - Add Exclusions

​Response

​get_property_list

​Resolving a property list reference

​Request - Get Resolved Properties

​Response

​Request - Get Metadata Only

​Response (Metadata Only)

​list_property_lists

​Request

​Response

​delete_property_list

​Request

​Response

​Integration with Other Tasks

​Using Lists in score_properties

​Using Lists in Media Buys

​Error Codes

​Caching and Refresh

​Usage Notes

Architecture: Setup Time, Not Real-Time

Tasks Overview

Property List Structure

Domain identifier format

Brand

Webhooks

Webhook Flow

Webhook Payload

Webhook Use Cases

Filters

Feature Requirements

Handling Missing Coverage

Required Filters

Filter Logic

Base Properties

create_property_list

Request

Response

Dynamic List (Filters Only)

update_property_list

Request - Update Filters

Request - Replace Base Properties

Request - Add Exclusions

Response

get_property_list

Resolving a property list reference

Request - Get Resolved Properties

Response

Request - Get Metadata Only

Response (Metadata Only)

list_property_lists

Request

Response

delete_property_list

Request

Response

Integration with Other Tasks

Using Lists in score_properties

Using Lists in Media Buys

Error Codes

Caching and Refresh

Usage Notes