IAB Tech Lab's reference buyer agent for DSPs, agencies and advertisers: an OpenAPI 3.1 REST surface (14 operations — orders and audit trails, booking jobs and approvals, product search, events, reports and campaign metadata) that drives MCP, A2A and REST clients against seller agents to browse media kits, negotiate and book OpenDirect 2.1 deals. Self-hosted; no IAB Tech Lab-hosted instance.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/buyer-agent-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
{
"openapi": "3.1.0",
"info": {
"title": "Ad Buyer Agent API",
"description": "Automated advertising buyer agent using CrewAI and IAB OpenDirect 2.1. Orchestrates budget allocation, inventory research, recommendation consolidation, and deal booking against seller agent APIs.",
"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": {
"/api/v1/buyer/orders": {
"get": {
"tags": [
"Buyer Orders"
],
"summary": "List Buyer Orders",
"description": "List buyer's orders from local DB with optional status filter.\n\nArgs:\n status: Optional status string to filter orders by.\n\nReturns:\n Dict with ``orders`` list and ``count``.",
"operationId": "list_buyer_orders_api_v1_buyer_orders_get",
"parameters": [
{
"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/buyer/orders/{order_id}/audit": {
"get": {
"tags": [
"Buyer Orders"
],
"summary": "Get Order Audit",
"description": "Get the local audit trail for an order.\n\nArgs:\n order_id: The order ID to query.\n\nReturns:\n Dict with order_id, current_status, transitions list,\n and transition_count.\n\nRaises:\n HTTPException(404): If the order is not found locally.",
"operationId": "get_order_audit_api_v1_buyer_orders__order_id__audit_get",
"parameters": [
{
"name": "order_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Order Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/health": {
"get": {
"tags": [
"Health"
],
"summary": "Health Check",
"description": "Health check endpoint.",
"operationId": "health_check_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Response Health Check Health Get"
}
}
}
}
}
}
},
"/bookings": {
"post": {
"tags": [
"Bookings"
],
"summary": "Create Booking",
"description": "Start a new booking workflow.\n\nCreates a background job that runs the full booking flow:\n1. Budget allocation\n2. Inventory research\n3. Recommendation consolidation\n4. (Optional) Automatic approval\n\nUse GET /bookings/{job_id} to check status.",
"operationId": "create_booking_bookings_post",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Bookings"
],
"summary": "List Bookings",
"description": "List all booking jobs.",
"operationId": "list_bookings_bookings_get",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response List Bookings Bookings Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/bookings/{job_id}": {
"get": {
"tags": [
"Bookings"
],
"summary": "Get Booking Status",
"description": "Get status of a booking workflow.",
"operationId": "get_booking_status_bookings__job_id__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingStatus"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/bookings/{job_id}/approve": {
"post": {
"tags": [
"Bookings"
],
"summary": "Approve Recommendations",
"description": "Approve specific recommendations for booking.\n\nCall this endpoint after the job reaches 'awaiting_approval' status.\nPass the product IDs you want to approve for booking.",
"operationId": "approve_recommendations_bookings__job_id__approve_post",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovalRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response Approve Recommendations Bookings Job Id Approve Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/bookings/{job_id}/approve-all": {
"post": {
"tags": [
"Bookings"
],
"summary": "Approve All Recommendations",
"description": "Approve all recommendations for booking.",
"operationId": "approve_all_recommendations_bookings__job_id__approve_all_post",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response Approve All Recommendations Bookings Job Id Approve All Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/products/search": {
"post": {
"tags": [
"Products"
],
"summary": "Search Products",
"description": "Search available advertising products.",
"operationId": "search_products_products_search_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductSearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"type": "object",
"title": "Response Search Products Products Search Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/events": {
"get": {
"tags": [
"Events"
],
"summary": "List Events",
"description": "List events from the event bus.\n\nQueries the in-memory event bus for recent events, with optional\nfiltering by event_type, flow_id, or session_id.",
"operationId": "list_events_events_get",
"parameters": [
{
"name": "event_type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Type"
}
},
{
"name": "flow_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Flow Id"
}
},
{
"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": {
"type": "object",
"additionalProperties": true,
"title": "Response List Events Events Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/events/{event_id}": {
"get": {
"tags": [
"Events"
],
"summary": "Get Event",
"description": "Retrieve a single 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": {
"type": "object",
"additionalProperties": true,
"title": "Response Get Event Events Event Id Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/reports/{job_id}": {
"get": {
"tags": [
"Reporting"
],
"summary": "Get Campaign Report",
"description": "Get delivery reports for a completed booking job.\n\nFetches data from:\n- Meta Ads API (for social channel bookings \u2014 campaign insights)\n- Seller agent deal performance API (for orchestrator-booked lines,\n keyed by the seller-issued ``deal_id``)\n\nRequires META_ACCESS_TOKEN + META_AD_ACCOUNT_ID + META_PAGE_ID in .env\nfor Meta reporting.",
"operationId": "get_campaign_report_reports__job_id__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
},
{
"name": "date_range",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "last_30d",
"title": "Date Range"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response Get Campaign Report Reports Job Id Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/meta/campaigns": {
"get": {
"tags": [
"Reporting"
],
"summary": "Meta List Campaigns",
"description": "List Meta Ads campaigns directly from the ad account (no booking job required).\n\nReturns campaigns with id, name, status, and objective.\nRequires META_ACCESS_TOKEN and META_AD_ACCOUNT_ID in .env.",
"operationId": "meta_list_campaigns_meta_campaigns_get",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 10,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response Meta List Campaigns Meta Campaigns Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/meta/report": {
"get": {
"tags": [
"Reporting"
],
"summary": "Meta Direct Report",
"description": "Pull insights directly from Meta Ads by campaign ID(s).\n\nArgs:\n campaign_ids: Comma-separated Meta campaign IDs\n date_preset: last_7d | last_14d | last_30d | last_90d | this_month\n\nReturns spend, impressions, reach, clicks, CTR, CPM per campaign.\nRequires META_ACCESS_TOKEN and META_AD_ACCOUNT_ID in .env.",
"operationId": "meta_direct_report_meta_report_get",
"parameters": [
{
"name": "campaign_ids",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Campaign Ids"
}
},
{
"name": "date_preset",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "last_30d",
"title": "Date Preset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Response Meta Direct Report Meta Report Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ApprovalRequest": {
"properties": {
"approved_product_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Approved Product Ids"
}
},
"type": "object",
"required": [
"approved_product_ids"
],
"title": "ApprovalRequest",
"description": "Request to approve recommendations."
},
"BookingRequest": {
"properties": {
"brief": {
"$ref": "#/components/schemas/CampaignBrief"
},
"auto_approve": {
"type": "boolean",
"title": "Auto Approve",
"description": "Automatically approve all recommendations",
"default": false
}
},
"type": "object",
"required": [
"brief"
],
"title": "BookingRequest",
"description": "Request to start a booking workflow."
},
"BookingResponse": {
"properties": {
"job_id": {
"type": "string",
"title": "Job Id"
},
"status": {
"type": "string",
"title": "Status"
},
"message": {
"type": "string",
"title": "Message"
}
},
"type": "object",
"required": [
"job_id",
"status",
"message"
],
"title": "BookingResponse",
"description": "Response from booking creation."
},
"BookingStatus": {
"properties": {
"job_id": {
"type": "string",
"title": "Job Id"
},
"status": {
"type": "string",
"title": "Status"
},
"progress": {
"type": "number",
"title": "Progress"
},
"budget_allocations": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Budget Allocations"
},
"recommendations": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Recommendations"
},
"booked_lines": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Booked Lines"
},
"errors": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Errors"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
}
},
"type": "object",
"required": [
"job_id",
"status",
"progress",
"created_at",
"updated_at"
],
"title": "BookingStatus",
"description": "Status of a booking job."
},
"CampaignBrief": {
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"title": "Name"
},
"objectives": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Objectives"
},
"budget": {
"type": "number",
"exclusiveMinimum": 0.0,
"title": "Budget"
},
"start_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"title": "Start Date"
},
"end_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"title": "End Date"
},
"target_audience": {
"additionalProperties": true,
"type": "object",
"title": "Target Audience"
},
"kpis": {
"additionalProperties": true,
"type": "object",
"title": "Kpis"
},
"channels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Channels"
}
},
"type": "object",
"required": [
"name",
"objectives",
"budget",
"start_date",
"end_date",
"target_audience"
],
"title": "CampaignBrief",
"description": "Campaign brief for booking."
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ProductSearchRequest": {
"properties": {
"channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"min_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Min Price"
},
"max_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Max Price"
},
"limit": {
"type": "integer",
"maximum": 50.0,
"minimum": 1.0,
"title": "Limit",
"default": 10
}
},
"type": "object",
"title": "ProductSearchRequest",
"description": "Request to search products."
},
"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": "Health",
"description": "Service health and readiness"
},
{
"name": "Bookings",
"description": "Campaign booking workflow lifecycle"
},
{
"name": "Products",
"description": "Seller inventory product search"
},
{
"name": "Events",
"description": "Event bus query endpoints"
}
]
}