AAMP component · specification
iab-agentic-primitives
iab-agentic-primitives is an AAMP specification repository from IAB Tech Lab. The canonical shared wire contract imported by both reference agents. Not listed in the AAMP hub README.
| Property | Value |
|---|---|
| Version | v0.5.0 (1 commits past the tag) |
| Commit | 2fc7029f |
| Kind | specification |
| Substance | substantial |
| Listed in the hub README | No |
What this repository defines
8 request and response pairs and 29 object definitions. The wire contract both reference agents pin: 48 versioned JSON Schemas for the shared objects and the request/response protocol, plus an OpenAPI document. Its own README opens with WORK IN PROGRESS — NOT YET RELEASED.
Request and response pairs
| Message pair | Required | Summary |
|---|---|---|
AgentDiscovery | 1 | Request body for ``POST /registry/agents/discover``: fetch and register a counterparty's card by its base URL. |
Avails | 3 | Request body for ``POST /products/avails``. |
ChangeRequest | 0 | Success envelope wrapping the ChangeRequest primitive. |
DealBooking | 2 | Request body for ``POST /api/v1/deals`` (money-mutating: FD-12). |
JsonRpc | 2 | JSON-RPC 2.0 request envelope, pinned to ``message/send``. |
NegotiationRound | 0 | The seller's answer to a :class:`NegotiationMessage`. |
ProductList | 0 | Query parameters for ``GET /products`` (pagination only). |
Quote | 3 | Request body for ``POST /api/v1/quotes`` (money-mutating: FD-12). |
The objects, field by field
These come from the schema and interface files this repository checks in, under the names the source files use.
Account
Commercial relationship between a specific buyer and seller organization.
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Seller-issued account identifier. |
advertiser_id | one of several | Optional advertiser this account transacts for (buyer-supplied). | |
buyer_organization_id | string | required | Registry-issued id of the buying organization. |
ext | one of several | ||
name | one of several | ||
seller_organization_id | string | required | Registry-issued id of the selling organization. |
status | AccountStatus |
Agent
An advertising agent: A2A (agent-to-agent protocol) card plus registry identity.
Agent fields — 17 fields, 5 required
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | required | Registry-issued agent identifier. |
agent_type | AgentType | ||
audience_capabilities | one of several | Audience capability discovery block. | |
authentication | AgentAuthentication | ||
capabilities | AgentCapabilities | ||
contact | one of several | ||
description | string | required | |
inventory_types | string[] | ||
name | string | required | |
organization_id | one of several | Registry-issued id of the operating organization. | |
provider | AgentProvider | required | |
skills | AgentSkill[] | ||
supported_deal_types | string[] | DealType wire values the agent supports: 'PG' (Programmatic Guaranteed), 'PD' (Preferred Deal), 'PA' (Private Auction). | |
tos_url | one of several | Terms-of-service URL. | |
trust_status | TrustStatus | Registry-verified trust status. | |
url | string | required | A2A service endpoint. |
version | string |
Assignment
Binds a creative to a line with rotation rules.
| Field | Type | Required | Description |
|---|---|---|---|
assignment_id | string | required | Seller-issued assignment identifier. |
creative_id | string | required | |
effective_end_date | one of several | ||
effective_start_date | one of several | ||
ext | one of several | ||
line_id | string | required | Seller-issued line the creative runs on. |
rotation_mode | RotationMode | ||
sov | one of several | Share of voice (0-1) for weighted rotation. | |
status | one of several | Free-form assignment status; the typed vocabulary lands with the EP-1.4 state-machine bead. |
ChangeRequest
A request to modify an existing order or deal post-booking.
ChangeRequest fields — 20 fields, 2 required
| Field | Type | Required | Description |
|---|---|---|---|
applied_at | one of several | ||
applied_by | one of several | ||
approved_at | one of several | ||
approved_by | one of several | ||
availability_check | one of several | ||
change_request_id | string | required | Seller-issued change request identifier. |
change_type | ChangeType | required | |
deal_id | one of several | Deal being modified; at least one of order_id/deal_id. | |
diffs | FieldDiff[] | ||
makegood | one of several | Required when change_type == 'makegood' (FD-6). | |
order_id | one of several | Order being modified; at least one of order_id/deal_id. | |
pricing_impact | one of several | ||
proposed_values | object | ||
reason | string | ||
rejection_reason | one of several | ||
requested_at | string | ||
requested_by | string | Actor id: 'system', 'human:<id>', or 'agent:<id>'. | |
severity | ChangeSeverity | ||
status | ChangeRequestStatus | ||
validation_errors | string[] |
ConsentContext
Privacy consent signals that travel with a deal (flagged decision FD-10).
| Field | Type | Required | Description |
|---|---|---|---|
applicable_regimes | string[] | Privacy regime identifiers in scope (e.g. | |
diligence_status | DiligenceStatus | Counterparty diligence status (SGP = SafeGuard Privacy / IAB Diligence Platform). | |
gdpr_applies | one of several | Whether GDPR (EU General Data Protection Regulation) applies to this context; None when undetermined. | |
gpp_section_ids | integer[] | GPP section ids present in the string. | |
gpp_string | one of several | GPP (Global Privacy Platform) consent string. | |
tcf_string | one of several | TCF (Transparency & Consent Framework) TC string, when GDPR applies. | |
us_privacy | one of several | US Privacy (CCPA) string, e.g. | |
verified_at | one of several | Timezone-aware timestamp of the last diligence verification, if any. |
Creative
Creative metadata for an advertising asset.
Creative fields — 14 fields, 1 required
| Field | Type | Required | Description |
|---|---|---|---|
account_id | one of several | Seller-issued account the creative belongs to. | |
ad_product_taxonomy | one of several | IAB Ad Product Taxonomy classification. | |
ad_profile | AdProfile | ||
audience_taxonomy | one of several | IAB Audience Taxonomy classification. | |
click_url | one of several | ||
content_policy | one of several | ||
creative_id | string | required | Seller-issued creative identifier. |
creative_manifest | CreativeManifest | ||
ext | one of several | Extension slot. | |
is_placeholder | boolean | ||
language | one of several | ISO 639-1 language code. | |
name | one of several | ||
placeholder_type | one of several | ||
review_status | ReviewStatus | Seller-side approval state (plan §4.4). |
CreativeApproval
A durable seller-side creative approval decision (EP-10.5).
| Field | Type | Required | Description |
|---|---|---|---|
approval_id | string | required | Seller-issued approval decision identifier. |
creative_id | string | required | Seller-issued id of the creative reviewed. |
ext | one of several | Extension slot. | |
occurred_at | string | Timezone-aware UTC timestamp of the review decision. | |
reason | one of several | Rationale, required in practice for a rejection. | |
reviewer | string | required | Actor id: 'system', 'human:<id>', or 'agent:<id>'. |
status | ReviewStatus | required | Outcome of this review decision. |
Deal
A confirmed deal booked from a quote (Deals API v1.0 book phase).
Deal fields — 18 fields, 5 required
| Field | Type | Required | Description |
|---|---|---|---|
activation_instructions | object | ||
buyer_tier | AccessTier | ||
consent_context | one of several | Privacy consent signals riding with the deal (FD-10). | |
created_at | string | ||
deal_id | string | required | Seller-issued deal identifier. |
deal_type | DealType | required | |
expires_at | one of several | Acceptance window for a proposed deal. | |
linear_tv | one of several | Linear TV details carried over from the booked quote (FD-6). | |
media_type | MediaType | ||
openrtb_params | one of several | ||
pricing | QuotePricing | required | |
product | ProductRef | required | |
quote_id | one of several | Seller-issued id of the quote this deal booked. | |
rate_card_id | one of several | Seller-issued id of the private rate card this deal books against, when the pair has one (FD-9). | |
seller_id | one of several | Registry-issued id of the selling agent. | |
status | DealStatus | ||
supply_chain | one of several | OpenRTB supply chain (schain) for transparency (EP-10.3); optional so pre-schain deals still validate. | |
terms | QuoteTerms | required |
DecisionRecord
A durable record of why a money/state decision was made (EP-10.1).
DecisionRecord fields — 13 fields, 6 required
| Field | Type | Required | Description |
|---|---|---|---|
actor | DecisionActor | required | |
correlation_id | one of several | Correlation id linking related records/events. | |
decision_id | string | required | Id of this decision record (minted by the decider). |
decision_type | DecisionType | required | |
ext | one of several | Extension slot. | |
inputs | DecisionInputRef[] | References/hashes of the counterparty inputs and model outputs that drove the decision (never raw prompts). | |
money_effect | one of several | Money movement this decision caused, if any (exact micros; FD-11). | |
negotiation_id | one of several | Negotiation the decision belongs to, if any. | |
occurred_at | string | Timezone-aware UTC timestamp of when the decision was made. | |
rationale | DecisionRationale | required | |
session_id | one of several | Session the decision occurred in, if any. | |
subject_id | string | required | Id of the deal/quote/order/... |
subject_type | string | required | Type of the subject: 'deal', 'quote', 'order', 'negotiation', 'change_request'. |
Line
Individual product booking within an order (OpenDirect Line).
Line fields — 13 fields, 8 required
| Field | Type | Required | Description |
|---|---|---|---|
cost | one of several | Calculated cost (read-only, seller-computed). | |
end_date | string | required | |
ext | one of several | ||
line_id | string | required | Seller-issued line identifier. |
name | string | required | |
order_id | string | required | |
pricing_model | PricingModel | ||
product_id | string | required | |
quantity | integer | required | Target impressions or units. |
rate | Money | required | Rate per pricing-model unit (exact micros; FD-11). |
start_date | string | required | |
status | LineStatus | ||
targeting | one of several |
MediaKit
A seller's discoverable inventory catalog: the packages it offers buyers.
| Field | Type | Required | Description |
|---|---|---|---|
contact | one of several | ||
created_at | string | ||
currency | string | ISO 4217 currency code. | |
description | one of several | ||
media_kit_id | string | required | Seller-issued media kit identifier. |
name | string | required | |
packages | Package[] | ||
seller_organization_id | string | required | Registry-issued id of the publishing seller organization. |
updated_at | one of several |
Negotiation
Multi-turn offer history container for a buyer/seller negotiation.
| Field | Type | Required | Description |
|---|---|---|---|
buyer_tier | AccessTier | ||
completed_at | one of several | ||
negotiation_id | string | required | Seller-issued negotiation identifier. |
package_id | one of several | Set when negotiating on a package. | |
product_id | one of several | ||
proposal_id | one of several | Proposal under negotiation, if proposal-led. | |
quote_id | one of several | Quote under negotiation, if quote-led. | |
rounds | NegotiationRound[] | ||
started_at | string | ||
status | NegotiationStatus |
Order
Campaign container (insertion order) holding one or more lines.
Order fields — 14 fields, 6 required
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Seller-issued account identifier. |
budget | Money | required | Estimated budget (exact micros; FD-11). |
consent_context | one of several | Privacy consent signals riding with the order (FD-10). | |
created_at | string | ||
deal_id | one of several | Deal this order fulfils, if deal-led. | |
end_date | string | required | |
ext | one of several | ||
external_ids | one of several | Ad-server order references (e.g. | |
name | string | required | |
order_id | string | required | Seller-issued order identifier. |
proposal_id | one of several | Proposal this order materializes, if any. | |
start_date | string | required | |
status | OrderStatus | ||
updated_at | one of several |
Organization
Legal/commercial entity participating in the ecosystem.
| Field | Type | Required | Description |
|---|---|---|---|
address | one of several | ||
contacts | one of several | ||
ext | one of several | Extension slot. | |
name | string | required | |
organization_id | string | required | Registry-issued organization identifier. |
role | OrganizationRole | required | |
status | OrganizationStatus |
Package
Curated inventory package for media kit discovery.
Package fields — 20 fields, 2 required
| Field | Type | Required | Description |
|---|---|---|---|
ad_formats | string[] | ||
audience_capabilities | one of several | Audience capability declaration. | |
base_price | one of several | Public/blended list price, if disclosed. | |
cat | string[] | IAB Content Taxonomy category ids, e.g. | |
cattax | integer | Content taxonomy version: 1=CT1.0, 2=CT2.0, 3=CT3.0. | |
created_at | string | ||
description | one of several | ||
device_types | integer[] | AdCOM DeviceType integers. | |
geo_targets | string[] | ISO 3166-2 codes, e.g. | |
is_featured | boolean | ||
layer | PackageLayer | ||
name | string | required | |
package_id | string | required | Seller-issued package identifier. |
placements | PackagePlacement[] | ||
pricing_model | PricingModel | ||
pricing_type | PricingType | ||
seasonal_label | one of several | ||
status | PackageStatus | ||
tags | string[] | ||
updated_at | one of several |
Product
Sellable unit of publisher inventory.
Product fields — 16 fields, 3 required
| Field | Type | Required | Description |
|---|---|---|---|
ad_formats | string[] | OpenRTB (Open Real-Time Bidding) formats: "banner", "video", "native", "audio". | |
ad_product_targeting | one of several | IAB Ad Product Taxonomy targeting intent. | |
audience_targeting | one of several | IAB Audience Taxonomy targeting intent. | |
available_impressions | one of several | ||
base_price | one of several | Public list price, if disclosed; None when pricing is on request. | |
commercial_terms | one of several | ||
content_targeting | one of several | IAB Content Taxonomy targeting intent. | |
delivery_type | DeliveryType | ||
description | one of several | ||
domain | one of several | ||
ext | one of several | Extension slot. | |
name | string | required | |
pricing_model | PricingModel | ||
pricing_type | PricingType | ||
product_id | string | required | Seller-issued product identifier. |
seller_organization_id | string | required | Registry-issued id of the owning seller organization. |
Proposal
A structured buy proposal under negotiation between the pair.
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Seller-issued account identifier. |
created_at | string | ||
current_revision_number | integer | ||
end_date | string | required | |
ext | one of several | ||
lines | ProposalLine[] | ||
proposal_id | string | required | Seller-issued proposal identifier. |
proposal_thread_id | one of several | Stable id across all revisions of this negotiation, if threaded. | |
start_date | string | required | |
status | ProposalStatus | ||
updated_at | one of several |
Quote
A non-binding price quote from a seller (Deals API v1.0 quote phase).
Quote fields — 16 fields, 5 required
| Field | Type | Required | Description |
|---|---|---|---|
availability | one of several | ||
buyer_tier | AccessTier | ||
consent_context | one of several | Privacy consent signals riding with the quote (FD-10). | |
created_at | string | ||
deal_id | one of several | Seller-issued deal id, set once the quote is booked. | |
deal_type | DealType | required | |
expires_at | one of several | ||
linear_tv | one of several | Linear TV details; None for digital/CTV. | |
media_type | MediaType | ||
pricing | QuotePricing | required | |
product | ProductRef | required | |
quote_id | string | required | Seller-issued quote identifier. |
rate_card_id | one of several | Seller-issued id of the private rate card this quote prices against, when the pair has one (FD-9). | |
seller_id | one of several | Registry-issued id of the quoting seller agent. | |
status | QuoteStatus | ||
terms | QuoteTerms | required |
RateCard
The private, negotiated rates a specific buyer/seller pair has agreed to.
| Field | Type | Required | Description |
|---|---|---|---|
account_id | one of several | Seller-issued account the agreement rides on, if any. | |
buyer_organization_id | string | required | Registry-issued id of the buyer party to the agreement. |
created_at | string | ||
effective_from | string | required | First day the agreed rates apply. |
effective_to | one of several | Last day the agreed rates apply; None = open-ended. | |
entries | RateCardEntry[] | Negotiated product/format -> rate entries. | |
notes | one of several | ||
rate_card_id | string | required | Seller-issued rate card identifier. |
seller_organization_id | string | required | Registry-issued id of the seller party to the agreement. |
status | RateCardStatus | ||
updated_at | one of several |
SellersJsonEntry
One entry from a system's sellers.json file.
| Field | Type | Required | Description |
|---|---|---|---|
comment | one of several | Optional free-text comment. | |
domain | one of several | Seller business domain; None when confidential. | |
ext | one of several | Extension slot. | |
is_confidential | boolean | True when name/domain are withheld (sellers.json is_confidential=1). | |
name | one of several | Seller business name; None when confidential. | |
seller_id | string | required | Opaque seller id, unique within the publishing system. |
seller_type | SellerType | required | PUBLISHER, INTERMEDIARY, or BOTH. |
Session
A persistent multi-turn buyer conversation with a seller.
| Field | Type | Required | Description |
|---|---|---|---|
active_deal_ids | string[] | ||
active_negotiation_ids | string[] | ||
buyer_identity | BuyerIdentity | ||
closed_at | one of several | ||
created_at | string | ||
expires_at | one of several | ||
messages | SessionMessage[] | ||
metadata | object | ||
session_id | string | required | Seller-issued session identifier. |
status | SessionStatus | ||
updated_at | string |
SupplyChain
OpenRTB SupplyChain object (``schain``): the ordered node path.
| Field | Type | Required | Description |
|---|---|---|---|
complete | integer | OpenRTB 0/1: 1 = all nodes in the path are disclosed. | |
ext | one of several | Extension slot. | |
nodes | SupplyChainNode[] | Supply path, ordered first-seller -> requesting-entity. | |
ver | string | SupplyChain object version (OpenRTB ``ver``). |
AgentTrustVerification
Registry-verified trust result for an agent (replaces the buyer's ``AgentTrustInfo``).
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | one of several | Registry-issued agent id, when registered. | |
agent_url | string | required | |
registry_id | one of several | Registry that answered, e.g. | |
trust_status | TrustStatus | ||
verified_at | one of several | Timezone-aware timestamp of the verification. |
Avails
Spec per-product RESPONSE record for ``POST /products/avails``.
| Field | Type | Required | Description |
|---|---|---|---|
accountid | string | required | Echo of the requesting account (spec-required). |
availability | one of several | Quantity available for booking in the date range. | |
availsstatus | one of several | Availability grouping (Available / Partially Available / Unavailable). | |
currency | one of several | ISO-4217 currency code. | |
enddate | string | required | Echo of the requested delivery end (spec-required). |
price | number | required | The product's price (spec-required; OpenDirect 2.1 float dialect, FD-11 exception). |
productid | string | required | Product the availability + pricing is for (spec-required). |
startdate | string | required | Echo of the requested delivery start (spec-required). |
Those are the first 24, in source order. The remaining 5 definitions in the repository are AvailsCollection, ChangeRequestCreate, ErrorEnvelope, NegotiationMessage, ProductAvailsSearch .