{ "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" } ] }