Every API here is available over the APIs.io API and to AI agents over MCP.
{
"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"
}
# --- truncated at 32 KB (276 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/iab-tech-lab/refs/heads/main/openapi/iab-tech-lab-seller-agent-openapi.json