{ "openapi": "3.1.0", "info": { "title": "Ad Seller System API", "description": "IAB OpenDirect 2.1 compliant seller agent for programmatic advertising. Supports product discovery, tiered pricing, proposal evaluation, multi-round negotiation, deal execution, order management, and change requests.", "contact": { "name": "IAB Tech Lab", "url": "https://iabtechlab.com/" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.0.0" }, "paths": { "/": { "get": { "tags": [ "Core" ], "summary": "Root", "description": "API root.", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health": { "get": { "tags": [ "Core" ], "summary": "Health", "description": "Health check endpoint.", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List Events", "description": "List events, optionally filtered by flow_id, event_type, or session_id.", "operationId": "list_events_events_get", "parameters": [ { "name": "flow_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow Id" } }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/events/{event_id}": { "get": { "tags": [ "Events" ], "summary": "Get Event", "description": "Get a specific event by ID.", "operationId": "get_event_events__event_id__get", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Event Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/api-keys": { "get": { "tags": [ "Authentication" ], "summary": "List Api Keys", "description": "List all API keys (metadata only, no secrets).", "operationId": "list_api_keys_auth_api_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "Authentication" ], "summary": "Create Api Key", "description": "Create a new API key for a buyer.\n\nThe response contains the full API key which is shown ONLY ONCE.\nStore it securely \u2014 it cannot be retrieved again.", "operationId": "create_api_key_auth_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/api-keys/{key_id}": { "get": { "tags": [ "Authentication" ], "summary": "Get Api Key Details", "description": "Get details for a specific API key.", "operationId": "get_api_key_details_auth_api_keys__key_id__get", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Authentication" ], "summary": "Revoke Api Key", "description": "Revoke an API key. Revoked keys return 401 on use.", "operationId": "revoke_api_key_auth_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/supply-chain": { "get": { "tags": [ "Supply Chain" ], "summary": "Get Supply Chain", "description": "Return sellers.json-based self-description of this seller instance.\n\nIf SELLERS_JSON_PATH is configured, parses the real sellers.json file\nper IAB spec. Otherwise returns a default single-node chain.\nAlso includes an OpenRTB-compatible schain object.", "operationId": "get_supply_chain_api_v1_supply_chain_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplyChainResponse" } } } } } } }, "/api/v1/rate-card": { "get": { "tags": [ "Pricing" ], "summary": "Get Rate Card", "description": "Get the current rate card (base CPMs by inventory type).\n\nThe rate card drives floor pricing during inventory sync and\ndeal creation. Can be updated via PUT to reflect ad server rate cards.", "operationId": "get_rate_card_api_v1_rate_card_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "put": { "tags": [ "Pricing" ], "summary": "Update Rate Card", "description": "Update the rate card with current base CPMs from ad server.\n\nPublishers should update this when their ad server rate cards change.\nThe pricing engine uses these values as base prices before applying\ntier discounts and volume adjustments.", "operationId": "update_rate_card_api_v1_rate_card_put", "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RateCardEntry" }, "type": "array", "title": "Entries" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/inventory-sync/status": { "get": { "tags": [ "Core" ], "summary": "Get Inventory Sync Status", "description": "Get the current status of the periodic inventory sync scheduler.", "operationId": "get_inventory_sync_status_api_v1_inventory_sync_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/inventory-sync/trigger": { "post": { "tags": [ "Core" ], "summary": "Trigger Inventory Sync", "description": "Manually trigger an inventory sync.\n\nArgs:\n incremental: If true, only sync items changed since last sync\n (based on stored sync watermark). Full sync if false or no\n previous watermark exists.", "operationId": "trigger_inventory_sync_api_v1_inventory_sync_trigger_post", "parameters": [ { "name": "incremental", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Incremental" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/inventory-sync/watermark": { "get": { "tags": [ "Core" ], "summary": "Get Sync Watermark", "description": "Get the last sync watermark (used for incremental sync).", "operationId": "get_sync_watermark_api_v1_inventory_sync_watermark_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/gam/orders": { "get": { "tags": [ "Reporting" ], "summary": "Gam List Orders", "description": "List recent GAM orders directly from the ad server.\n\nArgs:\n limit: Maximum number of orders to return (default 50)\n agent_created_only: If true, return only orders created by the agent\n (deals whose stored record carries a gam_order_id link)\n\nRequires GAM_ENABLED=true, GAM_NETWORK_CODE, GAM_JSON_KEY_PATH in .env.", "operationId": "gam_list_orders_gam_orders_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "agent_created_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Agent Created Only" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Gam List Orders Gam Orders Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gam/report": { "get": { "tags": [ "Reporting" ], "summary": "Gam Delivery Report", "description": "Pull a delivery report from GAM by order ID(s).\n\nArgs:\n order_ids: Comma-separated numeric GAM order IDs\n days: Look-back window in days (default 30)\n\nReturns order metadata, line items, and delivery data (impressions,\nclicks, revenue). Requires GAM_ENABLED=true, GAM_NETWORK_CODE,\nGAM_JSON_KEY_PATH in .env.", "operationId": "gam_delivery_report_gam_report_get", "parameters": [ { "name": "order_ids", "in": "query", "required": true, "schema": { "type": "string", "title": "Order Ids" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Days" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Gam Delivery Report Gam Report Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List Products", "description": "List products in the catalog (shared ProductListResponse).\n\nReads from the cached static catalog (see `_get_static_product_catalog`)\ninstead of running ProductSetupFlow per request \u2014 kicking off the flow\nspins up an OpenDirect MCP session that hangs in `session.initialize()`.\nBuyers filter client-side over the returned Product records (there is\ndeliberately no POST /products/search on the shared catalog surface).", "operationId": "list_products_products_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products/avails": { "post": { "tags": [ "Products" ], "summary": "Check Avails", "description": "OpenDirect availability check (shared avails contract, BOTH dialects).\n\nRequest/response models are the canonical\n``iab_agentic_primitives.protocol`` avails messages (EP-12 adoption).\nThe published OpenDirect 2.1 ``ProductAvailsSearch`` (multi-product\n``productids`` array + required ``accountid``/``advertiserbrandid``)\nand the legacy simplified profile (scalar ``productid``) are both\naccepted, discriminated by their mutually-exclusive required fields;\nthe response dialect follows the request dialect.\n\nAvailability is derived honestly from the cached static catalog:\nrequested impressions come from ``requestedImpressions`` (legacy) or\nthe minted Investment ``producttargeting`` entries (spec), else are\nbudget-derived at the product CPM, else fall back to the product's\n``minimum_impressions``; ``maximum_impressions`` (when set) caps\navailability. ``deliveryConfidence`` is OMITTED (no forecast data\nsource \u2014 never fabricated) and products with neither ``base_cpm`` nor\n``floor_cpm`` are a 422 \u2014 never a fabricated price. The request's\n``targeting`` field is accepted but not used for filtering.\nSee :func:`ad_seller.services.catalog_service.check_avails` for the\nfull policy.", "operationId": "check_avails_products_avails_post", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProductAvailsSearch" }, { "$ref": "#/components/schemas/AvailsRequest" } ], "title": "Request" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AvailsCollection" }, { "$ref": "#/components/schemas/AvailsResponse" } ], "title": "Response Check Avails Products Avails Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products/{product_id}": { "get": { "tags": [ "Products" ], "summary": "Get Product", "description": "Get a specific product (shared Product primitive, no wrapper).\n\nReads from the cached static catalog instead of running ProductSetupFlow\nper request (see `list_products` for rationale).", "operationId": "get_product_products__product_id__get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pricing": { "post": { "tags": [ "Pricing" ], "summary": "Get Pricing", "description": "Get pricing for a product based on buyer context.", "operationId": "get_pricing_pricing_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/discovery": { "post": { "tags": [ "Discovery" ], "summary": "Discovery Query", "description": "Process a discovery query about inventory.", "operationId": "discovery_query_discovery_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/products/{product_id}/inventory-type": { "post": { "tags": [ "Products" ], "summary": "Override Inventory Type", "description": "Override the auto-detected inventory type for a product.\n\nPublishers can correct misclassified inventory types from ad server sync\nor apply custom categorization. The override persists across future syncs.", "operationId": "override_inventory_type_api_v1_products__product_id__inventory_type_post", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTypeOverride" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Products" ], "summary": "Get Inventory Type Override", "description": "Get the current inventory type override for a product, if any.", "operationId": "get_inventory_type_override_api_v1_products__product_id__inventory_type_get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Products" ], "summary": "Delete Inventory Type Override", "description": "Remove an inventory type override, reverting to auto-detected type.", "operationId": "delete_inventory_type_override_api_v1_products__product_id__inventory_type_delete", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/proposals": { "post": { "tags": [ "Proposals" ], "summary": "Submit Proposal", "description": "Submit a proposal for review.", "operationId": "submit_proposal_proposals_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/proposals/{proposal_id}/counter": { "post": { "tags": [ "Negotiation" ], "summary": "Counter Proposal", "description": "Submit a counter-offer in an ongoing negotiation.\n\nLoads or creates a NegotiationHistory, evaluates the buyer's offer,\npersists the updated history, and emits a NEGOTIATION_ROUND event.\n\nEP-5.2: this endpoint previously applied NO trust-tier ceiling \u2014 a\nbuyer could self-assert ADVERTISER pricing by populating\nadvertiser_id. The claimed tier is now verified against the agent\nregistry (agent_url) or the API key; unverifiable claims floor.", "operationId": "counter_proposal_proposals__proposal_id__counter_post", "parameters": [ { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterOfferRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/proposals/{proposal_id}/negotiation": { "get": { "tags": [ "Negotiation" ], "summary": "Get Negotiation Status", "description": "Get full negotiation history for a proposal.", "operationId": "get_negotiation_status_proposals__proposal_id__negotiation_get", "parameters": [ { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/negotiations/messages": { "post": { "tags": [ "Negotiation" ], "summary": "Post Negotiation Message", "description": "Canonical negotiation surface \u2014 accepts the shared NegotiationMessage.\n\nThe seller now validates the SAME message the buyer emits: a required\n``action`` enum (accept/counter/reject/final_offer) plus ``buyer_price``\nas :class:`Money`. A well-formed counter no longer 422s (the historical\nbug). Priced actions (counter/final_offer) run the seller's untouched\nnegotiation engine; accept/reject are recorded as terminal rounds off\nthe existing history.", "operationId": "post_negotiation_message_api_v1_negotiations_messages_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiationMessage" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiationRoundResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/deals": { "post": { "tags": [ "Deals" ], "summary": "Generate Deal", "description": "Generate a deal from an accepted proposal.", "operationId": "generate_deal_deals_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals": { "post": { "tags": [ "Deal Booking" ], "summary": "Book Deal", "description": "Book a deal from a previously issued quote.\n\nThe seller validates the quote, generates a Deal ID, and returns\nconfirmed terms. This is the commit point \u2014 the quote becomes bound.\n\n**Wire format (proposal \u00a75.6 + \u00a76 row 14b):** the seller accepts both\naudience-plan content types --\n``application/vnd.ucp.embedding+json; v=1`` (legacy UCP carrier) and\n``application/vnd.iab.agentic-audiences+json; v=1`` (new IAB Agentic\nAudiences alias). FastAPI's body parsing is content-type-permissive, so\nboth names round-trip the same Pydantic model with no custom dependency\nneeded; the dual acceptance is exercised by\n``tests/unit/test_deal_booking_snapshot.py``.\n\n**Snapshot (proposal \u00a75.1 Step 2 + wire-format \u00a76.5):** when the request\ncarries an ``audience_plan``, the seller persists it verbatim as\n``audience_plan_snapshot`` against the deal record and returns the\nsnapshot plus a per-role ``audience_match_summary`` so the buyer can\nverify the booking. The snapshot is authoritative for the lifetime of\nthe deal -- if seller capabilities change mid-flight, the snapshot is\nhonored (see ``services/fulfillment.honor_audience_plan_snapshot``).\n\n**Forensic logging (proposal \u00a75.1 Step 2):** the\n``audience_plan_id`` hash is logged at INFO via\n``ad_seller.audience.booking``. The buyer logs the same hash on its\nside; matching entries are the cross-system anchor for dispute\nresolution.\n\n**Idempotency (FD-12):** the request carries a required\n``idempotency_key``. A replay with a key already booked returns the\nsame Deal without minting a second one (no duplicate side effect).", "operationId": "book_deal_api_v1_deals_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealBookingRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealBookingResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agentic-audience/match": { "post": { "tags": [ "Audience" ], "summary": "Agentic Audience Match", "description": "Match a buyer-supplied agentic `AudienceRef` against this seller.\n\nPer proposal \u00a75.7 + \u00a76 row 11. Returns a match score and quality bucket.\nThe score is mock-quality (deterministic from sha256 of `identifier`);\nthe real embedding-similarity model is Epic 2 (E2-2).\n\nBehavior:\n- Non-agentic refs return HTTP 400.\n- Sellers with no top-level agentic capability (legacy / agentic\n decommissioned) return `agentic_supported_by_seller=False`,\n `match_quality=\"POOR\"`, score 0.\n- Otherwise the score is deterministic per `identifier` and bucketed\n into `STRONG | MODERATE | WEAK | POOR`.", "operationId": "agentic_audience_match_agentic_audience_match_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgenticAudienceMatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/export": { "get": { "tags": [ "Deal Booking" ], "summary": "Export Deals", "description": "Export deals in DSP-native format for platform connectors.\n\nArgs:\n format: Export format \u2014 generic, ttd, dv360, amazon, xandr\n status: Filter by deal status (confirmed, proposed, cancelled)\n\nReturns deals formatted for the target DSP's import requirements.\nEnables buyer Phase 4D platform connectors to pull deals natively.\n\nNOTE (EP-8.4): this literal route is registered BEFORE the\n``/api/v1/deals/{deal_id}`` catch-all so it is not shadowed. FastAPI\nmatches routes in registration order, so static/literal paths must\nprecede their ``{param}`` sibling on the same method + prefix.", "operationId": "export_deals_api_v1_deals_export_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "generic", "title": "Format" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}": { "get": { "tags": [ "Deal Booking" ], "summary": "Get Deal By Id", "description": "Get the current status of a deal.\n\nPerforms a lazy expiry check for deals in 'proposed' status. Returns\nthe shared :class:`DealBookingResponse` (wraps the Deal primitive).", "operationId": "get_deal_by_id_api_v1_deals__deal_id__get", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealBookingResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/from-template": { "post": { "tags": [ "Deal Booking" ], "summary": "Create Deal From Template", "description": "Create a deal directly from template parameters (quote + auto-book).\n\nAccepts structured template params instead of requiring a pre-existing\nquote. Internally runs the pricing engine, validates the buyer's max_cpm\nagainst the floor price, and auto-books the deal if acceptable.\n\nReturns 201 with the created deal on success.\nReturns 422 when max_cpm is below the seller's floor price, including\nthe seller's minimum price in the response.\nReturns 401 for unauthenticated requests.", "operationId": "create_deal_from_template_api_v1_deals_from_template_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealFromTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealFromTemplateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/performance": { "get": { "tags": [ "Deal Performance" ], "summary": "Get Deal Performance", "description": "Return delivery stats for a deal.\n\nProvides performance feedback for buyer SPO (Supply Path Optimization).\nReturns placeholder/mock stats initially \u2014 real ad server integration\ncomes in a future phase.", "operationId": "get_deal_performance_api_v1_deals__deal_id__performance_get", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/bulk": { "post": { "tags": [ "Bulk Operations" ], "summary": "Bulk Deal Operations", "description": "Process a batch of deal operations (create/update/cancel).\n\nEnables the Deal Library buyer agent to efficiently manage multiple\ndeals in a single request. Each operation is processed independently\nand returns per-operation success/failure.", "operationId": "bulk_deal_operations_api_v1_deals_bulk_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDealRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDealResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/push": { "post": { "tags": [ "Deal Booking" ], "summary": "Push Deal To Buyers", "description": "Push a deal to one or more buyer endpoints via IAB Deals API v1.0.\n\nThe seller sends deal terms to buyer DSPs. Each buyer receives an\nHTTP POST with the full IAB Deal object and responds with acceptance status.\n\nThis is the standardized deal distribution path \u2014 alternative to\nSSP-mediated distribution (PubMatic, Index Exchange, etc.).", "operationId": "push_deal_to_buyers_api_v1_deals_push_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPushRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/buyer-status": { "get": { "tags": [ "Deal Booking" ], "summary": "Get Deal Buyer Status", "description": "Query a buyer for their acceptance status of a deal.\n\nPolls the buyer's deal status endpoint to check if the deal\nhas been approved, rejected, or is ready to serve.", "operationId": "get_deal_buyer_status_api_v1_deals__deal_id__buyer_status_get", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "buyer_url", "in": "query", "required": true, "schema": { "type": "string", "title": "Buyer Url" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/distribute": { "post": { "tags": [ "Deal Booking" ], "summary": "Distribute Deal Via Ssp", "description": "Distribute a deal through configured SSP(s).\n\nRoutes the deal to the appropriate SSP based on routing rules\nor explicit ssp_name. The SSP handles DSP-side distribution.\n\nSupports multiple SSPs: PubMatic (MCP), Index Exchange (REST),\nMagnite (REST), or any configured SSP connector.", "operationId": "distribute_deal_via_ssp_api_v1_deals_distribute_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSPDealDistributeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/ssp-troubleshoot": { "get": { "tags": [ "Deal Booking" ], "summary": "Troubleshoot Deal Via Ssp", "description": "Troubleshoot a deal via SSP diagnostics.\n\nCalls the SSP's troubleshooting tool (e.g., PubMatic's\ndeal_troubleshooting) to diagnose performance issues.", "operationId": "troubleshoot_deal_via_ssp_api_v1_deals__deal_id__ssp_troubleshoot_get", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "ssp_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Ssp Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/curators": { "get": { "tags": [ "Curators" ], "summary": "List Curators", "description": "List all registered curators.\n\nReturns curators who can create deals against this publisher's\ninventory. Agent Range is pre-registered as a day-one curator.", "operationId": "list_curators_api_v1_curators_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "Curators" ], "summary": "Register Curator", "description": "Register a new curator.\n\nCurators can then create deals against this publisher's inventory\nvia the /api/v1/deals/curated endpoint.", "operationId": "register_curator_api_v1_curators_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuratorRegistrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/curators/{curator_id}": { "get": { "tags": [ "Curators" ], "summary": "Get Curator", "description": "Get details for a specific curator.", "operationId": "get_curator_api_v1_curators__curator_id__get", "parameters": [ { "name": "curator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Curator Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/curated": { "post": { "tags": [ "Curators" ], "summary": "Create Curated Deal", "description": "Create a deal with curator overlay.\n\nThe curator's fee is added on top of the publisher's base price.\nThe curator appears as a node in the deal's schain. The buyer\npays the total CPM (publisher + curator fee).\n\nThe deal is created via the normal from-template flow, then\nenriched with curator identity, fee, and targeting overlay.", "operationId": "create_curated_deal_api_v1_deals_curated_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuratedDealRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/migrate": { "post": { "tags": [ "Deal Booking" ], "summary": "Migrate Deal", "description": "Migrate (replace) an existing deal with a new one.\n\nCreates a replacement deal with parent_deal_id lineage pointing\nto the old deal, then deprecates the old deal. The buyer's Deal\nJockey can follow the lineage chain to track deal evolution.\n\nReturns the new deal with lineage metadata.", "operationId": "migrate_deal_api_v1_deals__deal_id__migrate_post", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealMigrationRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/deprecate": { "post": { "tags": [ "Deal Booking" ], "summary": "Deprecate Deal", "description": "Deprecate a deal with reason and optional replacement.\n\nMarks the deal as deprecated rather than cancelled \u2014 preserving\nthe history that this deal was intentionally sunset. If a\nreplacement_deal_id is provided, creates a lineage link.\n\nThe buyer's Deal Library uses this to:\n- Know which deals to stop targeting\n- Follow lineage to the replacement deal\n- Feed SPO scoring (why was this path deprecated?)", "operationId": "deprecate_deal_api_v1_deals__deal_id__deprecate_post", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealDeprecationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/deals/{deal_id}/lineage": { "get": { "tags": [ "Deal Booking" ], "summary": "Get Deal Lineage", "description": "Get the lineage chain for a deal.\n\nWalks parent_deal_id backwards and replacement_deal_id forwards\nto show the full evolution of a deal through migrations.", "operationId": "get_deal_lineage_api_v1_deals__deal_id__lineage_get", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals": { "get": { "tags": [ "Approvals" ], "summary": "List Pending Approvals", "description": "List all pending approval requests. Requires authentication.", "operationId": "list_pending_approvals_approvals_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals/{approval_id}": { "get": { "tags": [ "Approvals" ], "summary": "Get Approval", "description": "Get a specific approval request and its response (if any).\n\nRequires authentication.", "operationId": "get_approval_approvals__approval_id__get", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Approval Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals/{approval_id}/decide": { "post": { "tags": [ "Approvals" ], "summary": "Decide Approval", "description": "Submit a human decision for a pending approval. Requires authentication.\n\nThe verified principal from the authenticated API key is stamped into\nthe audit record; ``body.decided_by`` is kept as a display label only.", "operationId": "decide_approval_approvals__approval_id__decide_post", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Approval Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals/{approval_id}/resume": { "post": { "tags": [ "Approvals" ], "summary": "Resume Flow", "description": "Resume a flow after an approval decision has been submitted.\n\nRequires authentication. Loads the flow state snapshot, applies the\ndecision, and returns the final result without re-running expensive\ncrew evaluations.", "operationId": "resume_flow_approvals__approval_id__resume_post", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Approval Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions": { "post": { "tags": [ "Sessions" ], "summary": "Create Session", "description": "Create a new buyer conversation session.", "operationId": "create_session_sessions_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Sessions" ], "summary": "List Sessions", "description": "List sessions, optionally filtered by buyer identity or status.", "operationId": "list_sessions_sessions_get", "parameters": [ { "name": "buyer_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Key" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}": { "get": { "tags": [ "Sessions" ], "summary": "Get Session", "description": "Get session details and conversation history.", "operationId": "get_session_sessions__session_id__get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/messages": { "post": { "tags": [ "Sessions" ], "summary": "Send Session Message", "description": "Send a message within a session and get a response.", "operationId": "send_session_message_sessions__session_id__messages_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/{session_id}/close": { "post": { "tags": [ "Sessions" ], "summary": "Close Session Endpoint", "description": "Close a session.", "operationId": "close_session_endpoint_sessions__session_id__close_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/media-kit": { "get": { "tags": [ "Media Kit" ], "summary": "Media Kit Overview", "description": "Public media kit catalog overview.", "operationId": "media_kit_overview_media_kit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/media-kit/packages": { "get": { "tags": [ "Media Kit" ], "summary": "List Media Kit Packages", "description": "List packages with public view (price ranges, no exact pricing).\n\nAccepts the same audience-filter triple as `GET /packages` so public\ndiscovery callers can narrow by audience type without authenticating.", "operationId": "list_media_kit_packages_media_kit_packages_get", "parameters": [ { "name": "layer", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Layer" } }, { "name": "featured_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Featured Only" } }, { "name": "audience_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Type" } }, { "name": "audience_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Id" } }, { "name": "audience_taxonomy_version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Taxonomy Version" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/media-kit/packages/{package_id}": { "get": { "tags": [ "Media Kit" ], "summary": "Get Media Kit Package", "description": "Get a single package with public view.", "operationId": "get_media_kit_package_media_kit_packages__package_id__get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Package Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/media-kit/search": { "post": { "tags": [ "Media Kit" ], "summary": "Search Media Kit", "description": "Search packages by keyword. Authenticated buyers get richer results.\n\nPer proposal \u00a75.7, the scoring corpus now includes\n`audience_capabilities.standard_segment_ids` +\n`audience_capabilities.contextual_segment_ids` alongside keywords/tags\n-- a query mentioning a known IAB segment ID ranks packages that\ndeclare it higher than packages that don't.\n\nThe optional `audience_filter` body field restricts results to packages\nthat match its type/id/version triple, parallel to `GET /packages`.", "operationId": "search_media_kit_media_kit_search_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaKitSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/packages": { "get": { "tags": [ "Packages" ], "summary": "List Packages", "description": "List packages with tier-gated view.\n\nAudience filter (proposal \u00a75.7):\n\n- `audience_type`: one of `standard` | `contextual` | `agentic`.\n- `audience_id`: taxonomy ID for standard/contextual; URI for agentic.\n Requires `audience_type` to disambiguate which capability list to\n search.\n- `audience_taxonomy_version`: optional version constraint; when unset\n the seller's lock-file version is authoritative.\n\nEmpty results return `[]`, not 404 -- matches the existing behavior for\nlayer/featured filters.", "operationId": "list_packages_packages_get", "parameters": [ { "name": "buyer_tier", "in": "query", "required": false, "schema": { "type": "string", "default": "public", "title": "Buyer Tier" } }, { "name": "agency_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" } }, { "name": "advertiser_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" } }, { "name": "layer", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Layer" } }, { "name": "audience_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Type" } }, { "name": "audience_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Id" } }, { "name": "audience_taxonomy_version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Taxonomy Version" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Packages" ], "summary": "Create Package", "description": "Create a curated package (Layer 2).", "operationId": "create_package_packages_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/packages/{package_id}": { "get": { "tags": [ "Packages" ], "summary": "Get Package", "description": "Get a single package with tier-gated view.", "operationId": "get_package_packages__package_id__get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Package Id" } }, { "name": "buyer_tier", "in": "query", "required": false, "schema": { "type": "string", "default": "public", "title": "Buyer Tier" } }, { "name": "agency_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" } }, { "name": "advertiser_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Packages" ], "summary": "Update Package", "description": "Update an existing package.", "operationId": "update_package_packages__package_id__put", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Package Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Updates" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Packages" ], "summary": "Delete Package", "description": "Archive a package (soft delete).", "operationId": "delete_package_packages__package_id__delete", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Package Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/packages/assemble": { "post": { "tags": [ "Packages" ], "summary": "Assemble Package", "description": "Assemble a dynamic package (Layer 3) from product IDs.\n\nProduct ids resolve catalog-first with storage fallback (issue #34) \u2014\nthe same resolution as ``POST /packages``. Zero resolution is a 422\nnaming the unresolved ids; partial resolution surfaces\n``unresolved_ids``/``warnings`` on the response.", "operationId": "assemble_package_packages_assemble_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicPackageRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/packages/sync": { "post": { "tags": [ "Packages" ], "summary": "Sync Packages", "description": "Trigger ad server inventory sync (Layer 1).", "operationId": "sync_packages_packages_sync_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/.well-known/agent.json": { "get": { "tags": [ "Agent Registry" ], "summary": "Agent Card", "description": "Serve this seller agent's card for A2A discovery.\n\nReturns an A2A-protocol-compliant agent card describing this\nseller's capabilities, supported protocols, and inventory types.\nBuyer agents and registries fetch this to discover the seller.", "operationId": "agent_card__well_known_agent_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/registry/agents": { "get": { "tags": [ "Agent Registry" ], "summary": "List Registered Agents", "description": "List agents in the local registry.\n\nFilterable by agent_type (buyer, seller, tool_provider, data_provider, other)\nand trust_status (unknown, registered, approved, preferred, blocked).", "operationId": "list_registered_agents_registry_agents_get", "parameters": [ { "name": "agent_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Type" } }, { "name": "trust_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trust Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/registry/agents/{agent_id}": { "get": { "tags": [ "Agent Registry" ], "summary": "Get Registered Agent", "description": "Get details for a specific registered agent.", "operationId": "get_registered_agent_registry_agents__agent_id__get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Agent Registry" ], "summary": "Remove Registered Agent", "description": "Remove an agent from the local registry.", "operationId": "remove_registered_agent_registry_agents__agent_id__delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/registry/agents/discover": { "post": { "tags": [ "Agent Registry" ], "summary": "Discover Agent", "description": "Discover an agent by URL.\n\nFetches the agent's card from .well-known/agent.json, checks\nall configured registries (AAMP + extras) for verification, and\nregisters the agent locally with appropriate trust status.", "operationId": "discover_agent_registry_agents_discover_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/registry/agents/{agent_id}/trust": { "put": { "tags": [ "Agent Registry" ], "summary": "Update Agent Trust", "description": "Update an agent's trust status.\n\nUse this to approve, prefer, or block agents. Trust status determines\nthe maximum access tier:\n- unknown \u2192 PUBLIC (price ranges only)\n- registered \u2192 SEAT (exact prices, no negotiation)\n- approved \u2192 ADVERTISER (full access)\n- preferred \u2192 ADVERTISER + custom pricing rules\n- blocked \u2192 403 rejected, zero data access", "operationId": "update_agent_trust_registry_agents__agent_id__trust_put", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTrustRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/quotes": { "post": { "tags": [ "Quotes" ], "summary": "Create Quote", "description": "Request a non-binding price quote from the seller.\n\nThe seller evaluates the request against existing pricing rules and\nreturns a quote with pricing, terms, and availability. Quotes are\nephemeral with a 24-hour TTL \u2014 no Deal ID is created.", "operationId": "create_quote_api_v1_quotes_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/quotes/{quote_id}": { "get": { "tags": [ "Quotes" ], "summary": "Get Quote", "description": "Retrieve a previously issued quote.\n\nReturns 410 Gone if the quote has expired.", "operationId": "get_quote_api_v1_quotes__quote_id__get", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Quote Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders": { "post": { "tags": [ "Orders" ], "summary": "Create Order", "description": "Create a new order and persist its state machine.", "operationId": "create_order_api_v1_orders_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Orders" ], "summary": "List Orders", "description": "List orders, optionally filtered by status.", "operationId": "list_orders_api_v1_orders_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders/report": { "get": { "tags": [ "Orders", "Audit" ], "summary": "Get Orders Report", "description": "Summary report across all orders.\n\nReturns counts by status, transition frequency by actor type,\nand average time-in-state metrics.", "operationId": "get_orders_report_api_v1_orders_report_get", "parameters": [ { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Date" } }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Date" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders/{order_id}": { "get": { "tags": [ "Orders" ], "summary": "Get Order", "description": "Get order current status and audit trail.", "operationId": "get_order_api_v1_orders__order_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders/{order_id}/history": { "get": { "tags": [ "Orders" ], "summary": "Get Order History", "description": "Get the full transition history for an order.", "operationId": "get_order_history_api_v1_orders__order_id__history_get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders/{order_id}/transition": { "post": { "tags": [ "Orders" ], "summary": "Transition Order", "description": "Transition an order to a new state.\n\nValidates the transition against the state machine rules and\nrecords the change in the audit log.", "operationId": "transition_order_api_v1_orders__order_id__transition_post", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionOrderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orders/{order_id}/audit": { "get": { "tags": [ "Audit" ], "summary": "Get Order Audit", "description": "Detailed audit log for an order with optional filters.\n\nFilters:\n - actor: filter transitions by actor (exact or prefix match)\n - from_date: ISO date, only transitions on or after this date\n - to_date: ISO date, only transitions on or before this date", "operationId": "get_order_audit_api_v1_orders__order_id__audit_get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } }, { "name": "actor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" } }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Date" } }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Date" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/change-requests": { "post": { "tags": [ "Change Requests" ], "summary": "Create Change Request", "description": "Submit a change request for an existing order.\n\nValidates the change against the current order state, classifies\nseverity, and routes to approval if needed.", "operationId": "create_change_request_api_v1_change_requests_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChangeRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Change Requests" ], "summary": "List Change Requests", "description": "List change requests, optionally filtered by order or status.", "operationId": "list_change_requests_api_v1_change_requests_get", "parameters": [ { "name": "order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/change-requests/{cr_id}": { "get": { "tags": [ "Change Requests" ], "summary": "Get Change Request", "description": "Get a change request by ID.", "operationId": "get_change_request_api_v1_change_requests__cr_id__get", "parameters": [ { "name": "cr_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cr Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/change-requests/{cr_id}/review": { "post": { "tags": [ "Change Requests" ], "summary": "Review Change Request", "description": "Approve or reject a pending change request.", "operationId": "review_change_request_api_v1_change_requests__cr_id__review_post", "parameters": [ { "name": "cr_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cr Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewChangeRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/change-requests/{cr_id}/apply": { "post": { "tags": [ "Change Requests" ], "summary": "Apply Change Request", "description": "Apply an approved change request to the order.\n\nUpdates the order with the proposed values from the change request.", "operationId": "apply_change_request_api_v1_change_requests__cr_id__apply_post", "parameters": [ { "name": "cr_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cr Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AccessTier": { "type": "string", "enum": [ "public", "seat", "agency", "advertiser" ], "title": "AccessTier", "description": "Access tier for tiered pricing, derived from revealed buyer identity.\n\n- ``public``: no identity \u2014 price ranges only\n- ``seat``: authenticated DSP (demand-side platform) seat\n- ``agency``: agency identity revealed\n- ``advertiser``: advertiser identity revealed (best rates)" }, "AgenticAudienceMatchRequest": { "properties": { "audience_ref": { "additionalProperties": true, "type": "object", "title": "Audience Ref" }, "package_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Package Id" } }, "type": "object", "required": [ "audience_ref" ], "title": "AgenticAudienceMatchRequest", "description": "API request model for POST /agentic-audience/match (proposal \u00a75.7).\n\nAccepts a single `AudienceRef` (must be `type=agentic`) and an optional\npackage_id scope. Returns a deterministic mock-quality match score and\nquality bucket. Real model is Epic 2 / E2-2." }, "ApprovalDecisionRequest": { "properties": { "decision": { "type": "string", "title": "Decision" }, "decided_by": { "type": "string", "title": "Decided By", "default": "anonymous" }, "reason": { "type": "string", "title": "Reason", "default": "" }, "modifications": { "additionalProperties": true, "type": "object", "title": "Modifications", "default": {} } }, "type": "object", "required": [ "decision" ], "title": "ApprovalDecisionRequest", "description": "Request to submit an approval decision." }, "AudienceFilterModel": { "properties": { "audience_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Type" }, "audience_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Id" }, "taxonomy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Taxonomy Version" } }, "type": "object", "title": "AudienceFilterModel", "description": "Optional audience filter sub-object on `POST /media-kit/search`.\n\nMirrors the query-param triple on `GET /packages`: type + id + version.\nWhen present, search results are restricted to packages whose\n`audience_capabilities` match. See proposal \u00a75.7." }, "Avails": { "properties": { "productid": { "type": "string", "maxLength": 36, "title": "Productid", "description": "Product the availability + pricing is for (spec-required)." }, "accountid": { "type": "string", "maxLength": 36, "title": "Accountid", "description": "Echo of the requesting account (spec-required)." }, "availability": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Availability", "description": "Quantity available for booking in the date range." }, "availsstatus": { "anyOf": [ { "$ref": "#/components/schemas/AvailsStatus" }, { "type": "null" } ], "description": "Availability grouping (Available / Partially Available / Unavailable)." }, "currency": { "anyOf": [ { "type": "string", "maxLength": 3 }, { "type": "null" } ], "title": "Currency", "description": "ISO-4217 currency code." }, "price": { "type": "number", "title": "Price", "description": "The product's price (spec-required; OpenDirect 2.1 float dialect, FD-11 exception)." }, "startdate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "Echo of the requested delivery start (spec-required)." }, "enddate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "Echo of the requested delivery end (spec-required)." } }, "type": "object", "required": [ "productid", "accountid", "price", "startdate", "enddate" ], "title": "Avails", "description": "Spec per-product RESPONSE record for ``POST /products/avails``.\n\n``price`` stays a float per the OpenDirect 2.1 decimal dialect (the\nFD-11 exception documented in the module docstring)." }, "AvailsCollection": { "properties": { "avails": { "items": { "$ref": "#/components/schemas/Avails" }, "type": "array", "title": "Avails", "description": "One Avails record per product in the request." } }, "type": "object", "required": [ "avails" ], "title": "AvailsCollection", "description": "Spec response envelope: the ``avails`` collection object.\n\nPer the spec's Collection Objects table the ``POST /products/avails``\nresponse must be an object whose array property is named ``avails``\n(one record per requested product; empty when nothing matches)." }, "AvailsRequest": { "properties": { "productid": { "type": "string", "title": "Productid", "description": "Product to check." }, "startdate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "Flight start (ISO-8601)." }, "enddate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "Flight end (ISO-8601); must be after startdate." }, "requestedImpressions": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Requestedimpressions", "description": "Requested volume; when omitted the seller derives it from budget at the product CPM, else the product minimum." }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Budget", "description": "Budget in currency units (OpenDirect 2.1 float dialect \u2014 see the module docstring for the FD-11 exception)." }, "targeting": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Targeting", "description": "Requested targeting slices; sellers without per-slice availability data accept but do not filter on it." } }, "type": "object", "required": [ "productid", "startdate", "enddate" ], "title": "AvailsRequest", "description": "Request body for ``POST /products/avails``.\n\nSpec-named fields use the OpenDirect 2.1 all-lowercase wire names;\nthe extension fields (``requestedImpressions``/``budget``/\n``targeting``) keep their camelCase names. When neither\n``requestedImpressions`` nor ``budget`` is sent, the seller falls back\nto the product's minimum impressions." }, "AvailsResponse": { "properties": { "productid": { "type": "string", "title": "Productid", "description": "Echo of the product." }, "availableImpressions": { "type": "integer", "minimum": 0.0, "title": "Availableimpressions", "description": "REQUIRED (policy 1). Products without a capacity cap report the requested volume as available." }, "guaranteedImpressions": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Guaranteedimpressions", "description": "Present ONLY for PG-capable products (policy 3); omitted otherwise." }, "estimatedCpm": { "type": "number", "title": "Estimatedcpm", "description": "CPM the availability is priced at (base CPM, falling back to floor CPM). OpenDirect 2.1 float dialect (FD-11 exception)." }, "totalCost": { "type": "number", "title": "Totalcost", "description": "availableImpressions / 1000 * estimatedCpm, rounded to 2 decimals. OpenDirect 2.1 float dialect (FD-11 exception)." }, "deliveryConfidence": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Deliveryconfidence", "description": "Forecast confidence percentage. OPTIONAL \u2014 OMITTED entirely when the seller has no forecast data source (policy 2); never fabricated." }, "availableTargeting": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Availabletargeting", "description": "Targeting dimensions the product supports; omitted when the product declares none." } }, "type": "object", "required": [ "productid", "availableImpressions", "estimatedCpm", "totalCost" ], "title": "AvailsResponse", "description": "Response body for ``POST /products/avails``.\n\nHonest-availability policy: every number is derived from catalog\ndata \u2014 nothing is fabricated. Optional fields with no value are\nOMITTED from the wire, not sent as ``null`` (readers tolerate ``null``\nfrom pre-contract emitters)." }, "AvailsStatus": { "properties": { "status": { "$ref": "#/components/schemas/AvailsStatusValue", "description": "Available, Partially Available, or Unavailable." }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/AvailsStatusReason" }, { "type": "null" } ], "description": "Spec-enumerated reason when Partially Available or Unavailable." }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment", "description": "Free-text availability comment." }, "context": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductTargeting" }, "type": "array" }, { "type": "null" } ], "title": "Context", "description": "ProductTargeting entries describing the context of a Partially Available or Unavailable status." }, "producttargeting": { "items": { "$ref": "#/components/schemas/ProductTargeting" }, "type": "array", "title": "Producttargeting", "description": "ProductTargeting entries describing the inventory at this status (spec-required)." } }, "type": "object", "required": [ "status", "producttargeting" ], "title": "AvailsStatus", "description": "Spec ``Object: AvailsStatus`` \u2014 availability grouping for a product." }, "AvailsStatusReason": { "type": "string", "enum": [ "Booked", "Optioned", "Excluded", "OutOfCharge", "Prohibited", "Manual Trade Only", "InvalidPeriodLength", "InvalidFrameID", "InvalidBudget", "InvalidPrice", "ClientDuplication", "LocationDuplication", "LocationJuxta" ], "title": "AvailsStatusReason", "description": "Spec ``AvailsStatus.reason``: why inventory is not fully available." }, "AvailsStatusValue": { "type": "string", "enum": [ "Available", "Partially Available", "Unavailable" ], "title": "AvailsStatusValue", "description": "Spec ``AvailsStatus.status`` (note the space in the middle value)." }, "BulkDealOperation": { "properties": { "action": { "type": "string", "title": "Action" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Id" }, "quote_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quote Id" }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/QuoteBuyerIdentityModel" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "required": [ "action" ], "title": "BulkDealOperation", "description": "A single operation in a bulk deal request." }, "BulkDealOperationResult": { "properties": { "index": { "type": "integer", "title": "Index" }, "action": { "type": "string", "title": "Action" }, "success": { "type": "boolean", "title": "Success" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "index", "action", "success" ], "title": "BulkDealOperationResult", "description": "Result of a single bulk operation." }, "BulkDealRequest": { "properties": { "operations": { "items": { "$ref": "#/components/schemas/BulkDealOperation" }, "type": "array", "title": "Operations" } }, "type": "object", "required": [ "operations" ], "title": "BulkDealRequest", "description": "Batch of deal operations." }, "BulkDealResponse": { "properties": { "total": { "type": "integer", "title": "Total" }, "succeeded": { "type": "integer", "title": "Succeeded" }, "failed": { "type": "integer", "title": "Failed" }, "results": { "items": { "$ref": "#/components/schemas/BulkDealOperationResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "total", "succeeded", "failed", "results" ], "title": "BulkDealResponse", "description": "Batch results for bulk deal operations." }, "BuyerIdentity": { "properties": { "seat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Id", "description": "DSP seat identifier." }, "seat_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Name", "description": "DSP platform display name." }, "dsp_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dsp Platform", "description": "DSP platform slug (e.g. 'ttd', 'dv360')." }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "agency_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Name" }, "agency_holding_company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Holding Company" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "advertiser_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Name" }, "advertiser_industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Industry" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Id", "description": "Optional campaign scope for campaign-specific deals." }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Name" } }, "type": "object", "title": "BuyerIdentity", "description": "Buyer identity revealed progressively to unlock better pricing.\n\nSuperset of the buyer repo's ``BuyerIdentity`` and the seller repo's\n``BuyerIdentity``/``QuoteBuyerIdentity``; every field is optional so a\npartially revealed identity is always representable. The tier derived\nfrom these fields is capped server-side by the registry-verified trust\nstatus of the calling agent \u2014 it is never self-asserted." }, "CancellationTerms": { "properties": { "notice_days": { "type": "integer", "title": "Notice Days", "description": "Days of notice required before cancellation." }, "cancellable_pct": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Cancellable Pct", "description": "Portion of the deal that can be cancelled (0.0-1.0)." }, "deadline": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Deadline", "description": "Absolute deadline for cancellation." }, "force_majeure": { "type": "boolean", "title": "Force Majeure", "description": "Whether force majeure exceptions apply.", "default": true } }, "type": "object", "required": [ "notice_days", "cancellable_pct" ], "title": "CancellationTerms", "description": "Structured cancellation window for linear TV deals." }, "CommercialTerms": { "properties": { "supported_deal_types": { "items": { "$ref": "#/components/schemas/DealType" }, "type": "array", "title": "Supported Deal Types", "description": "Supported deal types: 'PG' (Programmatic Guaranteed), 'PD' (Preferred Deal), 'PA' (Private Auction)." }, "supported_pricing_models": { "items": { "$ref": "#/components/schemas/PricingModel" }, "type": "array", "title": "Supported Pricing Models" }, "minimum_deal_value": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "guarantee_allowed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Guarantee Allowed" }, "makegood_allowed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Makegood Allowed" } }, "type": "object", "title": "CommercialTerms", "description": "Commercial capabilities a product supports (not binding terms)." }, "ConsentContext": { "properties": { "applicable_regimes": { "items": { "type": "string" }, "type": "array", "title": "Applicable Regimes", "description": "Privacy regime identifiers in scope (e.g. 'GDPR', 'CCPA')." }, "gpp_string": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gpp String", "description": "GPP (Global Privacy Platform) consent string." }, "gpp_section_ids": { "items": { "type": "integer" }, "type": "array", "title": "Gpp Section Ids", "description": "GPP section ids present in the string." }, "tcf_string": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tcf String", "description": "TCF (Transparency & Consent Framework) TC string, when GDPR applies." }, "gdpr_applies": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Gdpr Applies", "description": "Whether GDPR (EU General Data Protection Regulation) applies to this context; None when undetermined. Gates interpretation of the TCF string." }, "us_privacy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Us Privacy", "description": "US Privacy (CCPA) string, e.g. '1YNN'; superseded by GPP where present." }, "diligence_status": { "$ref": "#/components/schemas/DiligenceStatus", "description": "Counterparty diligence status (SGP = SafeGuard Privacy / IAB Diligence Platform).", "default": "unknown" }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Verified At", "description": "Timezone-aware timestamp of the last diligence verification, if any." } }, "type": "object", "title": "ConsentContext", "description": "Privacy consent signals that travel with a deal (flagged decision FD-10).\n\nFull build-out (EP-10.4) of the EP-1.2 placeholder: the three\ninteroperable consent-string carriers \u2014 GPP (Global Privacy Platform)\nwith its applicable section ids, TCF (Transparency & Consent Framework)\nwith the ``gdpr_applies`` gate, and the US Privacy (``us_privacy``)\nstring \u2014 plus the SGP (SafeGuard Privacy / IAB Diligence Platform)\n``diligence_status``. Field names from the EP-1.2 placeholder are kept\nunchanged for backward compatibility; the build-out is purely additive.\nIt travels with the Deal, Quote, and Order. Strings are carried opaque:\nno decoding/vendor-list validation is claimed (see the conformance\nstandards registry)." }, "CounterOfferRequest": { "properties": { "buyer_price": { "type": "number", "title": "Buyer Price" }, "buyer_tier": { "type": "string", "title": "Buyer Tier", "default": "public" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "required": [ "buyer_price" ], "title": "CounterOfferRequest", "description": "Request to submit a counter-offer in a negotiation." }, "CreateApiKeyRequest": { "properties": { "seat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Id" }, "seat_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Name" }, "dsp_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dsp Platform" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "agency_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Name" }, "agency_holding_company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Holding Company" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "advertiser_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Name" }, "label": { "type": "string", "title": "Label", "default": "" }, "expires_in_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires In Days" } }, "type": "object", "title": "CreateApiKeyRequest", "description": "Request to create a new API key for a buyer." }, "CreateChangeRequestModel": { "properties": { "order_id": { "type": "string", "title": "Order Id" }, "change_type": { "type": "string", "title": "Change Type" }, "diffs": { "items": { "$ref": "#/components/schemas/FieldDiffModel" }, "type": "array", "title": "Diffs", "default": [] }, "proposed_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Proposed Values" }, "reason": { "type": "string", "title": "Reason", "default": "" }, "requested_by": { "type": "string", "title": "Requested By", "default": "system" } }, "type": "object", "required": [ "order_id", "change_type" ], "title": "CreateChangeRequestModel", "description": "Request to create a change request for an order." }, "CreateOrderRequest": { "properties": { "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Id" }, "quote_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quote Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "title": "CreateOrderRequest", "description": "Request to create a new order." }, "CreateSessionRequest": { "properties": { "seat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Id" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "is_authenticated": { "type": "boolean", "title": "Is Authenticated", "default": false }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "title": "CreateSessionRequest", "description": "Request to create a new session." }, "CuratedDealRequest": { "properties": { "curator_id": { "type": "string", "title": "Curator Id" }, "deal_type": { "type": "string", "title": "Deal Type", "default": "PMP" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "max_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Cpm" }, "impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impressions" }, "flight_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight End" }, "buyer_seat_ids": { "items": { "type": "string" }, "type": "array", "title": "Buyer Seat Ids", "default": [] }, "audience_segments": { "items": { "type": "string" }, "type": "array", "title": "Audience Segments", "default": [] }, "content_categories": { "items": { "type": "string" }, "type": "array", "title": "Content Categories", "default": [] } }, "type": "object", "required": [ "curator_id" ], "title": "CuratedDealRequest", "description": "Request to create a curated deal." }, "CuratorRegistrationRequest": { "properties": { "curator_id": { "type": "string", "title": "Curator Id" }, "name": { "type": "string", "title": "Name" }, "domain": { "type": "string", "title": "Domain" }, "curator_type": { "type": "string", "title": "Curator Type", "default": "full_service" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "fee_type": { "type": "string", "title": "Fee Type", "default": "percent" }, "fee_value": { "type": "number", "title": "Fee Value", "default": 0.0 }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key" }, "audience_segments": { "items": { "type": "string" }, "type": "array", "title": "Audience Segments", "default": [] }, "content_categories": { "items": { "type": "string" }, "type": "array", "title": "Content Categories", "default": [] }, "supported_deal_types": { "items": { "type": "string" }, "type": "array", "title": "Supported Deal Types", "default": [ "pmp", "preferred", "pg" ] } }, "type": "object", "required": [ "curator_id", "name", "domain" ], "title": "CuratorRegistrationRequest", "description": "Request to register a new curator." }, "Deal": { "properties": { "deal_id": { "type": "string", "title": "Deal Id", "description": "Seller-issued deal identifier." }, "deal_type": { "$ref": "#/components/schemas/DealType" }, "status": { "$ref": "#/components/schemas/DealStatus", "default": "proposed" }, "quote_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quote Id", "description": "Seller-issued id of the quote this deal booked." }, "rate_card_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rate Card Id", "description": "Seller-issued id of the private rate card this deal books against, when the pair has one (FD-9). Never embedded, only referenced." }, "product": { "$ref": "#/components/schemas/ProductRef" }, "pricing": { "$ref": "#/components/schemas/QuotePricing" }, "terms": { "$ref": "#/components/schemas/QuoteTerms" }, "buyer_tier": { "$ref": "#/components/schemas/AccessTier", "default": "public" }, "seller_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seller Id", "description": "Registry-issued id of the selling agent." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Acceptance window for a proposed deal." }, "activation_instructions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Activation Instructions" }, "openrtb_params": { "anyOf": [ { "$ref": "#/components/schemas/OpenRTBParams" }, { "type": "null" } ] }, "media_type": { "$ref": "#/components/schemas/MediaType", "default": "digital" }, "linear_tv": { "anyOf": [ { "$ref": "#/components/schemas/LinearTVQuoteDetails" }, { "type": "null" } ], "description": "Linear TV details carried over from the booked quote (FD-6)." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "consent_context": { "anyOf": [ { "$ref": "#/components/schemas/ConsentContext" }, { "type": "null" } ], "description": "Privacy consent signals riding with the deal (FD-10)." }, "supply_chain": { "anyOf": [ { "$ref": "#/components/schemas/SupplyChain" }, { "type": "null" } ], "description": "OpenRTB supply chain (schain) for transparency (EP-10.3); optional so pre-schain deals still validate." } }, "type": "object", "required": [ "deal_id", "deal_type", "product", "pricing", "terms" ], "title": "Deal", "description": "A confirmed deal booked from a quote (Deals API v1.0 book phase).\n\nID minting: ``deal_id`` is seller-issued." }, "DealBookingRequest": { "properties": { "idempotency_key": { "type": "string", "minLength": 1, "title": "Idempotency Key", "description": "Requester-minted opaque key (UUID recommended). Same key -> same response, no duplicate side effects (FD-12). Reusing a key with a different body is an idempotency_conflict error." }, "quote_id": { "type": "string", "title": "Quote Id", "description": "Seller-issued quote being booked." }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/BuyerIdentity" }, { "type": "null" } ], "description": "Must be consistent with the identity the quote was priced for; the seller re-verifies tier at booking." }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "audience_plan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Plan", "description": "Audience plan frozen with the booking (open object; typed model lands with the audience-plan bead). Unsupported parts are rejected structurally (FD-6) so the buyer can degrade and retry." }, "consent_context": { "anyOf": [ { "$ref": "#/components/schemas/ConsentContext" }, { "type": "null" } ], "description": "Privacy consent signals riding with the booking (FD-10)." } }, "type": "object", "required": [ "idempotency_key", "quote_id" ], "title": "DealBookingRequest", "description": "Request body for ``POST /api/v1/deals`` (money-mutating: FD-12).\n\nThis is the commit point \u2014 the referenced quote becomes bound. The\nseller mints ``deal_id`` in the response." }, "DealBookingResponse": { "properties": { "deal": { "$ref": "#/components/schemas/Deal" }, "audience_plan_snapshot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Plan Snapshot", "description": "Verbatim snapshot of the audience plan the booking carried, authoritative for the deal's lifetime. None for non-audience bookings." }, "audience_match_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Match Summary", "description": "Per-role match summary for the frozen plan (open object; typed model lands with the audience-plan bead)." } }, "type": "object", "required": [ "deal" ], "title": "DealBookingResponse", "description": "Success envelope for the deal endpoints: wraps the Deal primitive." }, "DealDeprecationRequest": { "properties": { "reason": { "type": "string", "title": "Reason" }, "replacement_deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Deal Id" } }, "type": "object", "required": [ "reason" ], "title": "DealDeprecationRequest", "description": "Request to deprecate a deal." }, "DealFromTemplateRequest": { "properties": { "deal_type": { "type": "string", "title": "Deal Type" }, "product_id": { "type": "string", "title": "Product Id" }, "impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impressions" }, "max_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Cpm" }, "flight_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight End" }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/QuoteBuyerIdentityModel" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "required": [ "deal_type", "product_id" ], "title": "DealFromTemplateRequest", "description": "Request model for POST /api/v1/deals/from-template." }, "DealFromTemplateResponse": { "properties": { "deal_id": { "type": "string", "title": "Deal Id" }, "status": { "type": "string", "title": "Status" }, "deal_type": { "type": "string", "title": "Deal Type" }, "product_id": { "type": "string", "title": "Product Id" }, "actual_price_cpm": { "type": "number", "title": "Actual Price Cpm" }, "currency": { "type": "string", "title": "Currency", "default": "USD" }, "impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impressions" }, "flight_start": { "type": "string", "title": "Flight Start" }, "flight_end": { "type": "string", "title": "Flight End" }, "buyer_tier": { "type": "string", "title": "Buyer Tier" }, "activation_instructions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Activation Instructions" }, "schain": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schain" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "deal_id", "status", "deal_type", "product_id", "actual_price_cpm", "flight_start", "flight_end", "buyer_tier", "activation_instructions", "created_at" ], "title": "DealFromTemplateResponse", "description": "Response for template-based deal creation." }, "DealMigrationRequest": { "properties": { "old_deal_id": { "type": "string", "title": "Old Deal Id" }, "deal_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Type" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "max_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Cpm" }, "impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impressions" }, "flight_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight End" }, "buyer_seat_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Buyer Seat Ids" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/QuoteBuyerIdentityModel" }, { "type": "null" } ] } }, "type": "object", "required": [ "old_deal_id" ], "title": "DealMigrationRequest", "description": "Request to migrate (replace) an existing deal." }, "DealPushRequest": { "properties": { "deal_id": { "type": "string", "title": "Deal Id" }, "buyer_urls": { "items": { "type": "string" }, "type": "array", "title": "Buyer Urls" }, "buyer_api_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Buyer Api Keys" }, "deal_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Type" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impressions" }, "flight_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flight End" }, "buyer_seat_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Buyer Seat Ids" } }, "type": "object", "required": [ "deal_id", "buyer_urls" ], "title": "DealPushRequest", "description": "Request to push a deal to buyer(s)." }, "DealRequest": { "properties": { "proposal_id": { "type": "string", "title": "Proposal Id" }, "dsp_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dsp Platform" } }, "type": "object", "required": [ "proposal_id" ], "title": "DealRequest", "description": "Request to generate a deal." }, "DealResponse": { "properties": { "deal_id": { "type": "string", "title": "Deal Id" }, "deal_type": { "type": "string", "title": "Deal Type" }, "price": { "type": "number", "title": "Price" }, "pricing_model": { "type": "string", "title": "Pricing Model" }, "openrtb_params": { "additionalProperties": true, "type": "object", "title": "Openrtb Params" }, "activation_instructions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Activation Instructions" } }, "type": "object", "required": [ "deal_id", "deal_type", "price", "pricing_model", "openrtb_params", "activation_instructions" ], "title": "DealResponse", "description": "Deal generation response." }, "DealStatus": { "type": "string", "enum": [ "proposed", "negotiating", "accepted", "booked", "active", "makegood_pending", "partially_cancelled", "completed", "rejected", "failed", "cancelled", "expired" ], "title": "DealStatus", "description": "ONE deal status vocabulary, unioned from the four competing sets.\n\nSources: buyer ``DealResponse.status`` (proposed/active/rejected/\nexpired/completed), seller ``DealBookingStatus`` (proposed/active/\nexpired/cancelled), buyer ``BuyerDealStatus`` (quoted/negotiating/\naccepted/booking/booked/delivering/... + linear TV extensions).\n\nRecorded aliases (retired values, NOT valid on the wire):\n``delivering`` -> ``active``; ``booking`` -> ``booked``;\n``quoted`` -> represented by QuoteStatus, not a deal state;\n``partially_canceled`` -> ``partially_cancelled``." }, "DealType": { "type": "string", "enum": [ "PG", "PD", "PA" ], "title": "DealType", "description": "Programmatic deal types. The short wire encoding is canonical.\n\n- ``PG`` = Programmatic Guaranteed: fixed price, guaranteed impressions\n- ``PD`` = Preferred Deal: fixed price, non-guaranteed first look\n- ``PA`` = Private Auction: auction with floor price, invited buyers\n\nMapping from the seller repo's retired long-form encoding\n(``models/core.py``): ``programmaticguaranteed`` -> ``PG``,\n``preferreddeal`` -> ``PD``, ``privateauction`` -> ``PA``. The\nlong-form strings are NOT valid wire values." }, "DeliveryType": { "type": "string", "enum": [ "Exclusive", "Guaranteed", "PMP" ], "title": "DeliveryType", "description": "Delivery type for a product (OpenDirect vocabulary).\n\nPMP = private marketplace." }, "DiligenceStatus": { "type": "string", "enum": [ "unknown", "pending", "passed", "failed" ], "title": "DiligenceStatus", "description": "Status of counterparty privacy diligence (IAB Diligence Platform)." }, "DiscoverAgentRequest": { "properties": { "agent_url": { "type": "string", "title": "Agent Url" } }, "type": "object", "required": [ "agent_url" ], "title": "DiscoverAgentRequest", "description": "Request to discover an agent by URL." }, "DiscoveryRequest": { "properties": { "query": { "type": "string", "title": "Query" }, "buyer_tier": { "type": "string", "title": "Buyer Tier", "default": "public" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "required": [ "query" ], "title": "DiscoveryRequest", "description": "Discovery query request." }, "DynamicPackageRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "product_ids": { "items": { "type": "string" }, "type": "array", "title": "Product Ids" } }, "type": "object", "required": [ "name", "product_ids" ], "title": "DynamicPackageRequest", "description": "Request to assemble a dynamic package from product IDs." }, "FieldDiffModel": { "properties": { "field": { "type": "string", "title": "Field" }, "old_value": { "title": "Old Value" }, "new_value": { "title": "New Value" } }, "type": "object", "required": [ "field" ], "title": "FieldDiffModel" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InventoryTypeOverride": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "inventory_type": { "type": "string", "title": "Inventory Type" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "product_id", "inventory_type" ], "title": "InventoryTypeOverride", "description": "Override inventory type classification for a product." }, "LinearTVParams": { "properties": { "target_demo": { "type": "string", "title": "Target Demo", "description": "Target demographic, e.g. \"A18-49\", \"A25-54\", \"HH\" (households)." }, "grps_requested": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Grps Requested", "description": "Requested volume in GRPs (gross rating points)." }, "dayparts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Dayparts", "description": "Target dayparts, e.g. \"primetime\", \"daytime\", \"late_night\"." }, "networks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Networks", "description": "Target networks, e.g. [\"NBC\", \"ESPN\"]." }, "dmas": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Dmas", "description": "Nielsen DMA (designated market area) codes; None means national." }, "spot_length": { "type": "integer", "title": "Spot Length", "description": "Spot length in seconds: 15, 30, or 60.", "default": 30 }, "target_cpp": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Buyer's desired CPP (cost per point)." }, "measurement_currency": { "type": "string", "title": "Measurement Currency", "description": "Audience measurement provider: \"nielsen\", \"comscore\", \"videoamp\".", "default": "nielsen" }, "rotation": { "type": "string", "title": "Rotation", "description": "Spot rotation: \"ros\" (run of schedule), \"fixed\", \"program_specific\".", "default": "ros" } }, "type": "object", "required": [ "target_demo" ], "title": "LinearTVParams", "description": "Linear-TV-specific request parameters (buyer-supplied).\n\nUsed when ``media_type == \"linear_tv\"``. GRP = gross rating point;\nCPP = cost per point; DMA = designated market area." }, "LinearTVQuoteDetails": { "properties": { "target_demo": { "type": "string", "title": "Target Demo" }, "estimated_grps": { "type": "number", "title": "Estimated Grps", "description": "Estimated GRPs (gross rating points)." }, "estimated_rating": { "type": "number", "title": "Estimated Rating" }, "cpp": { "$ref": "#/components/schemas/Money", "description": "CPP (cost per point) offered by the seller." }, "dayparts": { "items": { "type": "string" }, "type": "array", "title": "Dayparts" }, "networks": { "items": { "type": "string" }, "type": "array", "title": "Networks" }, "spots_per_week": { "type": "integer", "title": "Spots Per Week" }, "total_spots": { "type": "integer", "title": "Total Spots" }, "spot_length": { "type": "integer", "title": "Spot Length" }, "measurement_currency": { "type": "string", "title": "Measurement Currency" }, "audience_estimate": { "additionalProperties": true, "type": "object", "title": "Audience Estimate", "description": "Audience estimates; expected keys \"demo\", \"universe\", \"impressions_equiv\"." }, "cancellation_terms": { "anyOf": [ { "$ref": "#/components/schemas/CancellationTerms" }, { "type": "null" } ] }, "makegood_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Makegood Policy", "description": "Makegood policy: \"standard\" (audience deficiency unit), \"negotiated\", or \"none\"." } }, "type": "object", "required": [ "target_demo", "estimated_grps", "estimated_rating", "cpp", "dayparts", "networks", "spots_per_week", "total_spots", "spot_length", "measurement_currency" ], "title": "LinearTVQuoteDetails", "description": "Linear-TV-specific quote details (seller-populated).\n\nNested under ``Quote.linear_tv`` when ``media_type == \"linear_tv\"``." }, "MediaKitSearchRequest": { "properties": { "query": { "type": "string", "title": "Query" }, "buyer_tier": { "type": "string", "title": "Buyer Tier", "default": "public" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "audience_filter": { "anyOf": [ { "$ref": "#/components/schemas/AudienceFilterModel" }, { "type": "null" } ] } }, "type": "object", "required": [ "query" ], "title": "MediaKitSearchRequest", "description": "Request to search packages." }, "MediaType": { "type": "string", "enum": [ "digital", "ctv", "linear_tv" ], "title": "MediaType", "description": "Media type discriminator carried on quotes and deals.\n\nSellers that do not support ``linear_tv`` MUST return a structured\nrejection rather than silently mispricing (flagged decision FD-6);\nthe field exists on the shared schema so that rejection can be\nstructural." }, "Money": { "properties": { "amount_micros": { "type": "integer", "title": "Amount Micros", "description": "Amount in micros; 1,000,000 micros = 1 currency unit." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "title": "Currency", "description": "ISO 4217 alpha-3 currency code.", "default": "USD" } }, "type": "object", "required": [ "amount_micros" ], "title": "Money", "description": "Exact money amount in integer micros (flagged decision FD-11).\n\n``1_000_000`` micros = 1 currency unit \u2014 the ad-industry convention\n(Google Ad Manager, among others, prices in micros). Float is BANNED on\nthe wire for money: IEEE 754 floating point is non-deterministic for\nmoney math (``0.1 + 0.2 != 0.3``, and repeated CPM \u2014 cost per mille \u2014\narithmetic accumulates error), and the two source repos used ``float``\nend-to-end; that defect must not be fossilized into the spec. Every\nprice, rate, budget, and offer in the shared contract is a ``Money``.\n\n``amount_micros`` is a strict integer: float inputs are rejected at\nvalidation time rather than silently truncated." }, "NegotiationAction": { "type": "string", "enum": [ "accept", "counter", "reject", "final_offer" ], "title": "NegotiationAction", "description": "Action taken in a negotiation round." }, "NegotiationMessage": { "properties": { "idempotency_key": { "type": "string", "minLength": 1, "title": "Idempotency Key", "description": "Requester-minted opaque key (UUID recommended). Same key -> same response, no duplicate side effects (FD-12). Reusing a key with a different body is an idempotency_conflict error." }, "action": { "$ref": "#/components/schemas/NegotiationAction", "description": "REQUIRED move discriminator: 'accept', 'counter', 'reject' (walk-away), or 'final_offer'. No default \u2014 the action-less bare-price payload that caused the historical 422 does not validate." }, "negotiation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Negotiation Id", "description": "Seller-issued id of the negotiation to continue; None opens a new negotiation on proposal_id/quote_id." }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id", "description": "Proposal under negotiation, if proposal-led." }, "quote_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quote Id", "description": "Quote under negotiation, if quote-led." }, "round_number": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Round Number", "description": "The round the sender believes it is answering, for optimistic concurrency; a mismatch is a 'contention' error. The seller's numbering is authoritative." }, "buyer_price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The buyer's price this round (exact micros; FD-11). REQUIRED for 'counter'/'final_offer'; optional echo on 'accept'; omitted on 'reject'." }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/BuyerIdentity" }, { "type": "null" } ] }, "rationale": { "type": "string", "title": "Rationale", "description": "Optional human-readable rationale.", "default": "" } }, "type": "object", "required": [ "idempotency_key", "action" ], "title": "NegotiationMessage", "description": "A buyer negotiation move (money-mutating: FD-12).\n\nExactly one negotiation context is required: ``negotiation_id`` to\ncontinue, or ``proposal_id``/``quote_id`` to open (the seller mints\n``negotiation_id`` on open)." }, "NegotiationRound": { "properties": { "round_number": { "type": "integer", "minimum": 1.0, "title": "Round Number" }, "buyer_price": { "$ref": "#/components/schemas/Money", "description": "What the buyer offered this round." }, "seller_price": { "$ref": "#/components/schemas/Money", "description": "What the seller countered (or accepted at) this round." }, "action": { "$ref": "#/components/schemas/NegotiationAction" }, "concession_pct": { "type": "number", "title": "Concession Pct", "description": "Seller concession this round (0-1).", "default": 0.0 }, "cumulative_concession_pct": { "type": "number", "title": "Cumulative Concession Pct", "description": "Total seller concession so far (0-1).", "default": 0.0 }, "rationale": { "type": "string", "title": "Rationale", "default": "" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" } }, "type": "object", "required": [ "round_number", "buyer_price", "seller_price", "action" ], "title": "NegotiationRound", "description": "A single offer/counter round in a negotiation." }, "NegotiationRoundResponse": { "properties": { "negotiation_id": { "type": "string", "title": "Negotiation Id", "description": "Seller-issued negotiation identifier." }, "status": { "$ref": "#/components/schemas/NegotiationStatus", "description": "'active' or terminal ('accepted'/'rejected'/'expired'); terminal negotiations refuse further messages (negotiation_closed)." }, "round": { "$ref": "#/components/schemas/NegotiationRound" }, "rounds_remaining": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Rounds Remaining", "description": "Rounds left before the seller walks away, if disclosed." } }, "type": "object", "required": [ "negotiation_id", "status", "round" ], "title": "NegotiationRoundResponse", "description": "The seller's answer to a :class:`NegotiationMessage`.\n\nEmbeds the shared\n:class:`~iab_agentic_primitives.primitives.NegotiationRound` primitive\n\u2014 the same record appended to the Negotiation history \u2014 so the two\nsides cannot disagree about what a round contains. ``round.action`` is\nthe SELLER's move (accept/counter/reject/final_offer); when\n``status`` is terminal the round is the last one." }, "NegotiationStatus": { "type": "string", "enum": [ "active", "accepted", "rejected", "expired" ], "title": "NegotiationStatus", "description": "Status of a negotiation (typed; was a raw string in the seller repo)." }, "OpenRTBParams": { "properties": { "id": { "type": "string", "title": "Id", "description": "Deal id as it appears in the OpenRTB bid stream." }, "bidfloor": { "$ref": "#/components/schemas/Money", "description": "Bid floor (exact micros; FD-11). Adapters translate to the raw OpenRTB float `bidfloor`/`bidfloorcur` encoding at the DSP edge." }, "at": { "type": "integer", "title": "At", "description": "Auction type (3 = fixed price).", "default": 3 }, "wseat": { "items": { "type": "string" }, "type": "array", "title": "Wseat", "description": "Allowed buyer seats." }, "wadomain": { "items": { "type": "string" }, "type": "array", "title": "Wadomain", "description": "Allowed advertiser domains." } }, "type": "object", "required": [ "id", "bidfloor" ], "title": "OpenRTBParams", "description": "OpenRTB (Open Real-Time Bidding) deal parameters for DSP\n(demand-side platform) activation." }, "PackageCreateRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "product_ids": { "items": { "type": "string" }, "type": "array", "title": "Product Ids", "default": [] }, "cat": { "items": { "type": "string" }, "type": "array", "title": "Cat", "default": [] }, "cattax": { "type": "integer", "title": "Cattax", "default": 2 }, "audience_capabilities": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Capabilities" }, "audience_segment_ids": { "items": { "type": "string" }, "type": "array", "title": "Audience Segment Ids", "default": [] }, "device_types": { "items": { "type": "integer" }, "type": "array", "title": "Device Types", "default": [] }, "ad_formats": { "items": { "type": "string" }, "type": "array", "title": "Ad Formats", "default": [] }, "geo_targets": { "items": { "type": "string" }, "type": "array", "title": "Geo Targets", "default": [] }, "base_price": { "type": "number", "title": "Base Price" }, "floor_price": { "type": "number", "title": "Floor Price" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "default": [] }, "is_featured": { "type": "boolean", "title": "Is Featured", "default": false }, "seasonal_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seasonal Label" } }, "type": "object", "required": [ "name", "base_price", "floor_price" ], "title": "PackageCreateRequest", "description": "Request to create a curated package.\n\nAccepts the new typed `audience_capabilities` shape (proposal \u00a75.7).\nLegacy callers may still send `audience_segment_ids: list[str]` as\nflat input -- the field is retained as deprecated and will be folded\ninto `audience_capabilities.standard_segment_ids` (with implicit\nAT 1.1) by `create_package`." }, "PricingModel": { "type": "string", "enum": [ "cpm", "cpmv", "cpv", "cpc", "cpcv", "cpd", "cpp", "flat_fee", "unit_rate", "hybrid" ], "title": "PricingModel", "description": "Unit of pricing. Union of the buyer's ``RateType`` and the seller's\n``PricingModel`` plus the linear TV additions.\n\n- ``cpm``: cost per mille (thousand impressions)\n- ``cpmv``: cost per thousand viewable impressions\n- ``cpv``: cost per view\n- ``cpc``: cost per click\n- ``cpcv``: cost per completed view\n- ``cpd``: cost per day\n- ``cpp``: cost per (gross rating) point \u2014 linear TV\n- ``flat_fee``: flat fee (buyer repo's ``FlatRate`` maps here)\n- ``unit_rate``: per-unit rate\n- ``hybrid``: mixed CPM/CPP pricing \u2014 linear TV" }, "PricingRequest": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "buyer_tier": { "type": "string", "title": "Buyer Tier", "default": "public" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "volume": { "type": "integer", "title": "Volume", "default": 0 }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "required": [ "product_id" ], "title": "PricingRequest", "description": "Request for pricing information." }, "PricingResponse": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "base_price": { "type": "number", "title": "Base Price" }, "final_price": { "type": "number", "title": "Final Price" }, "currency": { "type": "string", "title": "Currency" }, "tier_discount": { "type": "number", "title": "Tier Discount" }, "volume_discount": { "type": "number", "title": "Volume Discount" }, "rationale": { "type": "string", "title": "Rationale" } }, "type": "object", "required": [ "product_id", "base_price", "final_price", "currency", "tier_discount", "volume_discount", "rationale" ], "title": "PricingResponse", "description": "Pricing response." }, "PricingType": { "type": "string", "enum": [ "fixed", "floor", "on_request" ], "title": "PricingType", "description": "How a price signal should be interpreted.\n\n- ``fixed``: price is set by the seller, use as-is\n- ``floor``: minimum price; negotiation expected above this level\n- ``on_request``: no price available; buyer must negotiate before any\n pricing exists (pricing fields are None \u2014 buyers must never fabricate\n a price for on_request inventory)" }, "Product": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Seller-issued product identifier." }, "seller_organization_id": { "type": "string", "title": "Seller Organization Id", "description": "Registry-issued id of the owning seller organization." }, "name": { "type": "string", "maxLength": 128, "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "base_price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Public list price, if disclosed; None when pricing is on request." }, "pricing_type": { "$ref": "#/components/schemas/PricingType", "default": "fixed" }, "pricing_model": { "$ref": "#/components/schemas/PricingModel", "default": "cpm" }, "delivery_type": { "$ref": "#/components/schemas/DeliveryType", "default": "Guaranteed" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "ad_formats": { "items": { "type": "string" }, "type": "array", "title": "Ad Formats", "description": "OpenRTB (Open Real-Time Bidding) formats: \"banner\", \"video\", \"native\", \"audio\"." }, "audience_targeting": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Targeting", "description": "IAB Audience Taxonomy targeting intent." }, "ad_product_targeting": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ad Product Targeting", "description": "IAB Ad Product Taxonomy targeting intent." }, "content_targeting": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content Targeting", "description": "IAB Content Taxonomy targeting intent." }, "available_impressions": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Available Impressions" }, "commercial_terms": { "anyOf": [ { "$ref": "#/components/schemas/CommercialTerms" }, { "type": "null" } ] }, "ext": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ext", "description": "Extension slot." } }, "type": "object", "required": [ "product_id", "seller_organization_id", "name" ], "title": "Product", "description": "Sellable unit of publisher inventory.\n\nMerges the buyer's OpenDirect (the IAB direct-buying API standard)\n``Product`` with the seller's taxonomy-driven ``Product``. Targeting\nintent uses the three IAB (Interactive Advertising Bureau) taxonomies:\nAudience (who sees the ad), Ad Product (what is advertised), and\nContent (where ads appear).\n\n``base_price`` is the seller's public/list price signal, if disclosed;\nthe private negotiated rate for a buyer/seller pair lives on their\nRateCard (flagged decision FD-9), never here.\n\nID minting: ``product_id`` is seller-issued." }, "ProductAvailsSearch": { "properties": { "productids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Productids", "description": "Products to get availability + pricing for (spec-required, non-empty)." }, "targeting": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Targeting", "description": "AdCOM Segment object array ({\"name\": , \"value\": })." }, "producttargeting": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductTargeting" }, "type": "array" }, { "type": "null" } ], "title": "Producttargeting", "description": "ProductTargeting entries to target for the availability request." }, "accountid": { "type": "string", "maxLength": 36, "title": "Accountid", "description": "Account identifying the buyer, advertiser, and other stakeholders (spec-required)." }, "currency": { "anyOf": [ { "type": "string", "maxLength": 3 }, { "type": "null" } ], "title": "Currency", "description": "ISO-4217 currency code." }, "advertiserbrandid": { "type": "string", "maxLength": 36, "title": "Advertiserbrandid", "description": "Brand being advertised (spec-required)." }, "availabilityfields": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductTargeting" }, "type": "array" }, { "type": "null" } ], "title": "Availabilityfields", "description": "ProductTargeting metrics availability is returned as." }, "grouping": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductTargeting" }, "type": "array" }, { "type": "null" } ], "title": "Grouping", "description": "ProductTargeting metrics the availability output is grouped by." }, "startdate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "Desired delivery start (ISO-8601)." }, "enddate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "Desired delivery end (ISO-8601); must be after startdate." } }, "type": "object", "required": [ "productids", "accountid", "advertiserbrandid", "startdate", "enddate" ], "title": "ProductAvailsSearch", "description": "Spec REQUEST body for ``POST /products/avails``.\n\nThe published multi-product form: ``productids`` is an array, and\n``accountid``/``advertiserbrandid`` are required. Use\n:meth:`to_simplified` to bridge to the legacy single-product queries\n(one per product id), recovering any minted Investment extension\nentries (requested volume / budget) and the Segment-array targeting." }, "ProductListResponse": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Product" }, "type": "array", "title": "Products" }, "total_count": { "type": "integer", "minimum": 0.0, "title": "Total Count", "description": "Total products in the catalog, ignoring pagination." }, "limit": { "type": "integer", "minimum": 1.0, "title": "Limit", "description": "Echo of the applied limit." }, "offset": { "type": "integer", "minimum": 0.0, "title": "Offset", "description": "Echo of the applied offset." } }, "type": "object", "required": [ "total_count", "limit", "offset" ], "title": "ProductListResponse", "description": "Response envelope for ``GET /products``." }, "ProductRef": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Seller-issued product identifier." }, "name": { "type": "string", "title": "Name" }, "inventory_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inventory Type" } }, "type": "object", "required": [ "product_id", "name" ], "title": "ProductRef", "description": "Lightweight product summary embedded in quotes and deals." }, "ProductTargeting": { "properties": { "name": { "$ref": "#/components/schemas/TargetingDimension", "description": "What is described: Inventory, Delivery, Distribution, Investment, or Prohibitions." }, "type": { "$ref": "#/components/schemas/TargetingUnit", "description": "How it is quantified: Frames, Audience, Investment, or Total." }, "datasource": { "type": "string", "maxLength": 255, "title": "Datasource", "description": "Data source that defines the target vocabulary (third-party schemas welcome by design)." }, "target": { "type": "string", "maxLength": 255, "title": "Target", "description": "The targeted metric within datasource." }, "targetvalues": { "items": { "type": "string" }, "type": "array", "title": "Targetvalues", "description": "One or more values for the target (strings on the wire)." }, "selectable": { "type": "boolean", "title": "Selectable", "description": "Whether a buyer may select from targetvalues or the values are fixed." }, "count": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Count", "description": "Count of targetvalues." }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Minimum", "description": "Minimum number of selectable targetvalues." }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Maximum", "description": "Maximum number of selectable targetvalues." }, "increment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Increment", "description": "Permitted increment between target values." }, "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ], "title": "Default", "description": "Default targetvalue(s) when the buyer selects none." } }, "type": "object", "required": [ "name", "type", "datasource", "target", "targetvalues", "selectable" ], "title": "ProductTargeting", "description": "Spec ``Object: ProductTargeting`` \u2014 dimensional targeting/metrics.\n\nAll-lowercase wire names per the normative table; the six starred\nattributes are required." }, "ProposalErrorDetail": { "properties": { "stage": { "type": "string", "title": "Stage" }, "code": { "type": "string", "title": "Code" }, "detail": { "type": "string", "title": "Detail", "default": "" } }, "type": "object", "required": [ "stage", "code" ], "title": "ProposalErrorDetail", "description": "Causeful machine-readable proposal error (seller issue #34).\n\nFD-6 structured-error house style: a stable snake_case ``code`` names\nthe cause (``missing_required_fields``, ``product_not_found``,\n``audience_validation``, ``pricing``, ``availability``,\n``crew_evaluation_error``, ``internal``), ``stage`` names the\nProposalHandlingFlow stage that failed the proposal, and ``detail``\ncarries the human-readable explanation." }, "ProposalRequest": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "deal_type": { "type": "string", "title": "Deal Type" }, "price": { "type": "number", "title": "Price" }, "impressions": { "type": "integer", "title": "Impressions" }, "start_date": { "type": "string", "title": "Start Date" }, "end_date": { "type": "string", "title": "End Date" }, "buyer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Id" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url" } }, "type": "object", "required": [ "product_id", "deal_type", "price", "impressions", "start_date", "end_date" ], "title": "ProposalRequest", "description": "Request to submit a proposal." }, "ProposalResponse": { "properties": { "proposal_id": { "type": "string", "title": "Proposal Id" }, "recommendation": { "type": "string", "title": "Recommendation" }, "status": { "type": "string", "title": "Status" }, "counter_terms": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Counter Terms" }, "approval_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Id" }, "pricing_verified": { "type": "boolean", "title": "Pricing Verified", "default": false }, "pricing_verification_reason": { "type": "string", "title": "Pricing Verification Reason", "default": "" }, "errors": { "items": { "$ref": "#/components/schemas/ProposalErrorDetail" }, "type": "array", "title": "Errors", "default": [] } }, "type": "object", "required": [ "proposal_id", "recommendation", "status" ], "title": "ProposalResponse", "description": "Proposal submission response.\n\nWire-compat note: a failed evaluation still answers HTTP 200 with\n``status=\"failed\"`` \u2014 but ``errors[]`` is now guaranteed non-empty and\ncauseful whenever the status is ``failed`` (seller issue #34)." }, "Quote": { "properties": { "quote_id": { "type": "string", "title": "Quote Id", "description": "Seller-issued quote identifier." }, "status": { "$ref": "#/components/schemas/QuoteStatus", "default": "available" }, "deal_type": { "$ref": "#/components/schemas/DealType" }, "product": { "$ref": "#/components/schemas/ProductRef" }, "pricing": { "$ref": "#/components/schemas/QuotePricing" }, "terms": { "$ref": "#/components/schemas/QuoteTerms" }, "availability": { "anyOf": [ { "$ref": "#/components/schemas/QuoteAvailability" }, { "type": "null" } ] }, "buyer_tier": { "$ref": "#/components/schemas/AccessTier", "default": "public" }, "rate_card_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rate Card Id", "description": "Seller-issued id of the private rate card this quote prices against, when the pair has one (FD-9). The rate card itself is never embedded." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "seller_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seller Id", "description": "Registry-issued id of the quoting seller agent." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Id", "description": "Seller-issued deal id, set once the quote is booked." }, "media_type": { "$ref": "#/components/schemas/MediaType", "default": "digital" }, "linear_tv": { "anyOf": [ { "$ref": "#/components/schemas/LinearTVQuoteDetails" }, { "type": "null" } ], "description": "Linear TV details; None for digital/CTV." }, "consent_context": { "anyOf": [ { "$ref": "#/components/schemas/ConsentContext" }, { "type": "null" } ], "description": "Privacy consent signals riding with the quote (FD-10)." } }, "type": "object", "required": [ "quote_id", "deal_type", "product", "pricing", "terms" ], "title": "Quote", "description": "A non-binding price quote from a seller (Deals API v1.0 quote phase).\n\nCarries ``media_type`` and optional ``linear_tv`` details on the shared\nschema (flagged decision FD-6) so sellers that do not support linear TV\ncan reject structurally instead of silently mispricing.\n\nID minting: ``quote_id`` is seller-issued." }, "QuoteAvailability": { "properties": { "inventory_available": { "type": "boolean", "title": "Inventory Available", "default": true }, "estimated_fill_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Fill Rate" }, "competing_demand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Competing Demand" } }, "type": "object", "title": "QuoteAvailability", "description": "Inventory availability information in a quote." }, "QuoteBuyerIdentityModel": { "properties": { "seat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seat Id" }, "agency_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency Id" }, "advertiser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser Id" }, "dsp_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dsp Platform" } }, "type": "object", "title": "QuoteBuyerIdentityModel", "description": "Buyer identity in a quote request." }, "QuotePricing": { "properties": { "pricing_type": { "$ref": "#/components/schemas/PricingType", "default": "fixed" }, "base_cpm": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "tier_discount_pct": { "type": "number", "title": "Tier Discount Pct", "default": 0.0 }, "volume_discount_pct": { "type": "number", "title": "Volume Discount Pct", "default": 0.0 }, "final_cpm": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "pricing_model": { "$ref": "#/components/schemas/PricingModel", "default": "cpm" }, "rationale": { "type": "string", "title": "Rationale", "default": "" }, "base_cpp": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Linear TV base CPP; None for digital/CTV." }, "final_cpp": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Linear TV final CPP; None for digital/CTV." } }, "type": "object", "title": "QuotePricing", "description": "Pricing breakdown on a quote or deal.\n\n``base_cpm``/``final_cpm`` are optional to support\n``pricing_type=on_request`` \u2014 when the seller has not provided pricing,\nthese fields are None. CPM = cost per mille (thousand impressions);\nCPP = cost per point (linear TV)." }, "QuoteRequest": { "properties": { "idempotency_key": { "type": "string", "minLength": 1, "title": "Idempotency Key", "description": "Requester-minted opaque key (UUID recommended). Same key -> same response, no duplicate side effects (FD-12). Reusing a key with a different body is an idempotency_conflict error." }, "product_id": { "type": "string", "title": "Product Id", "description": "Seller-issued product to quote." }, "deal_type": { "$ref": "#/components/schemas/DealType", "description": "'PG' (Programmatic Guaranteed), 'PD' (Preferred Deal), 'PA' (Private Auction). Typed \u2014 the retired long-form strings are not valid wire values." }, "impressions": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Impressions", "description": "Requested volume; required for PG." }, "flight_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Flight End" }, "target_cpm": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Buyer's desired CPM (exact micros; FD-11). Advisory." }, "buyer_identity": { "anyOf": [ { "$ref": "#/components/schemas/BuyerIdentity" }, { "type": "null" } ], "description": "Progressively revealed identity for tiered pricing; the effective tier is capped server-side by registry-verified trust." }, "agent_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Url", "description": "A2A endpoint of the requesting buyer agent, for registry trust verification. The buyer already sent this; the seller's model dropped it \u2014 now part of the contract." }, "rate_card_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rate Card Id", "description": "Seller-issued id of the pair's private rate card to price against (FD-9). The rate card itself never crosses the wire." }, "media_type": { "$ref": "#/components/schemas/MediaType", "description": "Media discriminator (FD-6). Sellers that do not support the requested type MUST reject structurally.", "default": "digital" }, "linear_tv": { "anyOf": [ { "$ref": "#/components/schemas/LinearTVParams" }, { "type": "null" } ], "description": "Linear TV parameters; required when media_type == 'linear_tv', must be None otherwise." }, "audience_plan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audience Plan", "description": "Audience plan slot (open object; the typed model lands with the audience-plan bead). Sellers pre-flight it against their capabilities and reject unsupported parts structurally (FD-6)." }, "consent_context": { "anyOf": [ { "$ref": "#/components/schemas/ConsentContext" }, { "type": "null" } ], "description": "Privacy consent signals riding with the request (FD-10)." } }, "type": "object", "required": [ "idempotency_key", "product_id", "deal_type" ], "title": "QuoteRequest", "description": "Request body for ``POST /api/v1/quotes`` (money-mutating: FD-12).\n\nID minting: the seller mints ``quote_id`` in the response; the buyer\nnever proposes one." }, "QuoteResponse": { "properties": { "quote": { "$ref": "#/components/schemas/Quote" } }, "type": "object", "required": [ "quote" ], "title": "QuoteResponse", "description": "Success envelope for the quote endpoints: wraps the Quote primitive.\n\nThe quote carries its own ``media_type``, ``linear_tv`` details,\n``rate_card_id``, pricing, terms, availability, and ``expires_at``\n(quotes are ephemeral \u2014 the seller enforces a TTL and answers a\n``quote_expired`` error after it elapses)." }, "QuoteStatus": { "type": "string", "enum": [ "available", "booked", "expired", "declined" ], "title": "QuoteStatus", "description": "Status of a price quote (identical in both source repos)." }, "QuoteTerms": { "properties": { "impressions": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Impressions" }, "flight_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Flight Start" }, "flight_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Flight End" }, "guaranteed": { "type": "boolean", "title": "Guaranteed", "default": false }, "grps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Grps", "description": "Linear TV volume in GRPs (gross rating points)." }, "guaranteed_grps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Guaranteed Grps" }, "target_demo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Demo", "description": "Linear TV target demographic." } }, "type": "object", "title": "QuoteTerms", "description": "Volume, flight, and guarantee terms on a quote or deal." }, "RateCardEntry": { "properties": { "inventory_type": { "type": "string", "title": "Inventory Type" }, "base_cpm": { "type": "number", "title": "Base Cpm" }, "currency": { "type": "string", "title": "Currency", "default": "USD" }, "effective_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effective Date" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "required": [ "inventory_type", "base_cpm" ], "title": "RateCardEntry", "description": "Rate card entry mapping inventory type to base CPM." }, "ReviewChangeRequestModel": { "properties": { "decision": { "type": "string", "title": "Decision" }, "decided_by": { "type": "string", "title": "Decided By", "default": "system" }, "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "required": [ "decision" ], "title": "ReviewChangeRequestModel", "description": "Approve or reject a change request." }, "SSPDealDistributeRequest": { "properties": { "deal_id": { "type": "string", "title": "Deal Id" }, "deal_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deal Type", "default": "PMP" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "advertiser": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Advertiser" }, "cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cpm" }, "buyer_seat_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Buyer Seat Ids" }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" }, "targeting": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Targeting" }, "ssp_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ssp Name" }, "inventory_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inventory Type" } }, "type": "object", "required": [ "deal_id" ], "title": "SSPDealDistributeRequest", "description": "Request to distribute a deal through configured SSPs." }, "SessionMessageRequest": { "properties": { "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "SessionMessageRequest", "description": "Request to send a message within a session." }, "SupplyChain": { "properties": { "complete": { "type": "integer", "maximum": 1.0, "minimum": 0.0, "title": "Complete", "description": "OpenRTB 0/1: 1 = all nodes in the path are disclosed.", "default": 1 }, "ver": { "type": "string", "title": "Ver", "description": "SupplyChain object version (OpenRTB ``ver``).", "default": "1.0" }, "nodes": { "items": { "$ref": "#/components/schemas/SupplyChainNode" }, "type": "array", "title": "Nodes", "description": "Supply path, ordered first-seller -> requesting-entity." }, "ext": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ext", "description": "Extension slot." } }, "type": "object", "title": "SupplyChain", "description": "OpenRTB SupplyChain object (``schain``): the ordered node path.\n\n``complete`` is the OpenRTB 0/1 flag: 1 means every node from the\ninitial impression to the final bidder is present (no undisclosed\nhops). Nodes are ordered from the first seller to the entity making the\nrequest. Carried optionally on the :class:`Deal` for transparency." }, "SupplyChainNode": { "properties": { "asi": { "type": "string", "title": "Asi", "description": "Advertising system identifier (canonical domain of the system)." }, "sid": { "type": "string", "title": "Sid", "description": "Seller id within the ``asi`` system; matches its sellers.json seller_id." }, "hp": { "type": "integer", "maximum": 1.0, "minimum": 0.0, "title": "Hp", "description": "Handled-payment flag (OpenRTB 0/1): 1 = node is paid for this inventory.", "default": 1 }, "rid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rid", "description": "Request id issued by the seller (OpenRTB ``rid``), when present." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Business name of the entity represented by this node." }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Business domain of the entity represented by this node." }, "ext": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ext", "description": "Extension slot." } }, "type": "object", "required": [ "asi", "sid" ], "title": "SupplyChainNode", "description": "One hop in the OpenRTB supply chain (``schain`` node).\n\nField names are the OpenRTB SupplyChainNode names verbatim. ``asi`` is\nthe advertising system identifier (the canonical domain of the system\nthe node operates in, e.g. ``\"exchange.example.com\"``); ``sid`` is the\nseller id **within that system** and matches a ``seller_id`` in that\nsystem's sellers.json." }, "SupplyChainNodeModel": { "properties": { "asi": { "type": "string", "title": "Asi" }, "sid": { "type": "string", "title": "Sid" }, "name": { "type": "string", "title": "Name" }, "domain": { "type": "string", "title": "Domain" }, "seller_type": { "type": "string", "title": "Seller Type" }, "is_direct": { "type": "boolean", "title": "Is Direct" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment" } }, "type": "object", "required": [ "asi", "sid", "name", "domain", "seller_type", "is_direct" ], "title": "SupplyChainNodeModel", "description": "A node in the supply chain (sellers.json format)." }, "SupplyChainResponse": { "properties": { "seller_id": { "type": "string", "title": "Seller Id" }, "seller_name": { "type": "string", "title": "Seller Name" }, "seller_type": { "type": "string", "title": "Seller Type" }, "domain": { "type": "string", "title": "Domain" }, "is_direct": { "type": "boolean", "title": "Is Direct" }, "supported_deal_types": { "items": { "type": "string" }, "type": "array", "title": "Supported Deal Types" }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email" }, "schain": { "items": { "$ref": "#/components/schemas/SupplyChainNodeModel" }, "type": "array", "title": "Schain" }, "version": { "type": "string", "title": "Version", "default": "1.0" } }, "type": "object", "required": [ "seller_id", "seller_name", "seller_type", "domain", "is_direct", "supported_deal_types", "schain" ], "title": "SupplyChainResponse", "description": "Supply chain transparency response (sellers.json-like self-description)." }, "TargetingDimension": { "type": "string", "enum": [ "Inventory", "Delivery", "Distribution", "Investment", "Prohibitions" ], "title": "TargetingDimension", "description": "Spec ``ProductTargeting.name``: what the entry describes." }, "TargetingUnit": { "type": "string", "enum": [ "Frames", "Audience", "Investment", "Total" ], "title": "TargetingUnit", "description": "Spec ``ProductTargeting.type``: how the entry is quantified." }, "TransitionOrderRequest": { "properties": { "to_status": { "type": "string", "title": "To Status" }, "actor": { "type": "string", "title": "Actor", "default": "system" }, "reason": { "type": "string", "title": "Reason", "default": "" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "required": [ "to_status" ], "title": "TransitionOrderRequest", "description": "Request to transition an order to a new state." }, "UpdateTrustRequest": { "properties": { "trust_status": { "type": "string", "title": "Trust Status" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "required": [ "trust_status" ], "title": "UpdateTrustRequest", "description": "Request to update an agent's trust status." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "tags": [ { "name": "Core", "description": "Health check and API root" }, { "name": "Products", "description": "Product catalog browsing" }, { "name": "Pricing", "description": "Tiered pricing with buyer context" }, { "name": "Proposals", "description": "Proposal submission and evaluation" }, { "name": "Deals", "description": "Deal generation from accepted proposals" }, { "name": "Discovery", "description": "Natural language inventory discovery" }, { "name": "Events", "description": "Event bus log inspection" }, { "name": "Approvals", "description": "Human-in-the-loop approval workflow" }, { "name": "Sessions", "description": "Multi-turn buyer conversation sessions" }, { "name": "Negotiation", "description": "Multi-round price negotiation" }, { "name": "Media Kit", "description": "Public media kit and package catalog" }, { "name": "Packages", "description": "Package management (authenticated/admin)" }, { "name": "Authentication", "description": "API key lifecycle management" }, { "name": "Agent Registry", "description": "A2A agent discovery and trust management" }, { "name": "Quotes", "description": "Non-binding price quotes (IAB Deals API v1.0)" }, { "name": "Deal Booking", "description": "Quote-to-deal booking (IAB Deals API v1.0)" }, { "name": "Orders", "description": "Order state machine and lifecycle management" }, { "name": "Change Requests", "description": "Post-deal modification requests" }, { "name": "Audit", "description": "Order audit logs and operational reports" }, { "name": "Supply Chain", "description": "Supply chain transparency (sellers.json-like self-description)" }, { "name": "Deal Performance", "description": "Deal delivery and performance metrics" }, { "name": "Bulk Operations", "description": "Batch deal create/update/cancel" } ] }