On this page

control

Planes

Components

Version

per-repository; see components

Licence

Mixed — Apache-2.0, AGPL-3.0, CC BY

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.

Source: IABTechLab/iab-agentic-primitives

Version: v0.5.0 (1 commits past the tag)
Commit: 2fc7029f
Kind: specification
Substance: substantial
Listed in the hub README: No

iab-agentic-primitives on 12 August 2026: version, kind, substance grade and hub listing. Substance is an editorial grade rather than a measurement, on the ranking test.

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

iab-agentic-primitives — 8 request and response pairs. The Required column counts top-level required fields on the request, and does not recurse into nested objects.
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 7 fields

Commercial relationship between a specific buyer and seller organization.

Account fields — 7 fields, 3 required
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 17 fields

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 9 fields

Binds a creative to a line with rotation rules.

Assignment fields — 9 fields, 3 required
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 20 fields

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 8 fields

Privacy consent signals that travel with a deal (flagged decision FD-10).

ConsentContext fields — 8 fields, 0 required
Field	Type	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 14 fields

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 7 fields

A durable seller-side creative approval decision (EP-10.5).

CreativeApproval fields — 7 fields, 4 required
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 18 fields

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 13 fields

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 13 fields

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 9 fields

A seller's discoverable inventory catalog: the packages it offers buyers.

MediaKit fields — 9 fields, 3 required
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 10 fields

Multi-turn offer history container for a buyer/seller negotiation.

Negotiation fields — 10 fields, 1 required
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 14 fields

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 7 fields

Legal/commercial entity participating in the ecosystem.

Organization fields — 7 fields, 3 required
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 20 fields

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 16 fields

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 11 fields

A structured buy proposal under negotiation between the pair.

Proposal fields — 11 fields, 4 required
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 16 fields

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 11 fields

The private, negotiated rates a specific buyer/seller pair has agreed to.

RateCard fields — 11 fields, 4 required
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 7 fields

One entry from a system's sellers.json file.

SellersJsonEntry fields — 7 fields, 2 required
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 11 fields

A persistent multi-turn buyer conversation with a seller.

Session fields — 11 fields, 1 required
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 4 fields

OpenRTB SupplyChain object (``schain``): the ordered node path.

SupplyChain fields — 4 fields, 0 required
Field	Type	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 5 fields

Registry-verified trust result for an agent (replaces the buyer's ``AgentTrustInfo``).

AgentTrustVerification fields — 5 fields, 1 required
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 8 fields

Spec per-product RESPONSE record for ``POST /products/avails``.

Avails fields — 8 fields, 5 required
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.