{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/3.1.0-rc.4/media-buy/create-media-buy-response.json", "title": "Create Media Buy Response", "description": "Response payload for create_media_buy. Exactly one of three shapes: (1) synchronous success — media_buy_id and packages are issued in-line, media_buy_status MAY carry the lifecycle value (pending_creatives / pending_start / active), deprecated top-level status MAY carry the same MediaBuyStatus during the 3.1 migration window, and confirmed_at is either the seller commitment timestamp or null for a provisional buy that already exists; provisional buys with confirmed_at: null cannot be active and cannot carry packages[].committed_metrics; (2) terminal failure — an errors array with no media-buy artifact and status != 'submitted'; (3) submitted task envelope — status 'submitted' with task_id when no media_buy_id is being returned to the buyer and the media buy is queued or awaiting a human decision (e.g., IO signing). In the submitted branch, media_buy_id / packages land on the task's completion artifact, not this response. The submitted branch MAY carry advisory errors for non-blocking warnings; terminal failures belong in the error branch. These three shapes are mutually exclusive — a response has exactly one.", "type": "object", "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json" }, { "$ref": "/schemas/3.1.0-rc.4/core/protocol-envelope.json" } ], "oneOf": [ { "title": "CreateMediaBuySuccess", "description": "Success response - media buy created successfully", "type": "object", "properties": { "media_buy_id": { "type": "string", "description": "Seller's unique identifier for the created media buy", "x-entity": "media_buy" }, "account": { "$ref": "/schemas/3.1.0-rc.4/core/account.json", "description": "Account billed for this media buy. Includes advertiser, billing proxy (if any), and rate card applied." }, "invoice_recipient": { "$ref": "/schemas/3.1.0-rc.4/core/business-entity.json", "description": "Per-buy invoice recipient, echoed from the request when provided. Confirms the seller accepted the billing override. Bank details are omitted (write-only)." }, "media_buy_status": { "$ref": "/schemas/3.1.0-rc.4/enums/media-buy-status.json", "description": "Initial media buy status. Either 'pending_creatives' (awaiting creative assets), 'pending_start' (ready to serve, waiting for flight date), or 'active' (immediate activation). Added in 3.1: at the top level of flat-on-the-wire MCP responses, the `status` key is reserved for the envelope TaskStatus (`completed` on synchronous success). Sellers SHOULD emit `media_buy_status` from 3.1 onward; the legacy top-level `status: MediaBuyStatus` form is deprecated and removed in 3.2 (#4906). When the deprecated `status` is also present during the 3.1 deprecation window, both MUST carry identical values — divergent emission is a conformance violation flagged by 3.1 compliance storyboards." }, "status": { "$ref": "/schemas/3.1.0-rc.4/enums/media-buy-status.json", "deprecated": true, "description": "DEPRECATED in 3.1, removed in 3.2 (#4906). Use `media_buy_status` instead. Top-level `status` here collides with the envelope TaskStatus on flat-serialized MCP wire (see adcontextprotocol/adcp#4895). Buyers consuming 3.1+ responses MUST prefer `media_buy_status` when present; sellers MAY emit both during the deprecation window but MUST emit identical values when doing so — divergent emission is a conformance violation." }, "confirmed_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 timestamp when this media buy was committed by the seller. Stable after it is set; do not update on later pause/resume/status/reporting transitions. May be null in deferred or manual-approval flows until seller commitment occurs." }, "creative_deadline": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for creative upload deadline" }, "revision": { "type": "integer", "description": "Initial revision number for this media buy. Use in subsequent update_media_buy requests intended to change state for optimistic concurrency.", "minimum": 1 }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP) for monetary values at this media buy level. total_budget is denominated in this currency. Package-level fields may override with package.currency. In proposal mode the seller derives this from the request's total_budget object (total_budget.currency); in manual mode it is present when all packages share a currency. Matches the currency field in subsequent get_media_buys responses.", "pattern": "^[A-Z]{3}$" }, "total_budget": { "type": "number", "description": "Total budget amount across all packages, denominated in currency. Note: the create_media_buy request encodes total_budget as an object {amount, currency} (proposal mode only); this response field is the flattened scalar amount, with currency promoted to the sibling currency field. Present when the seller can compute a deterministic aggregate — always in proposal mode, conditionally in manual mode when all packages share a currency. Matches the total_budget field in subsequent get_media_buys responses.", "minimum": 0 }, "valid_actions": { "type": "array", "description": "Flat-vocabulary actions the buyer can perform on this media buy after creation. Saves a round-trip to get_media_buys. Deprecated in favor of `available_actions[]`, which carries `mode`, optional SLA, and optional `terms_ref`. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer `available_actions[]` when both are present. Removed in 4.0.", "items": { "$ref": "/schemas/3.1.0-rc.4/enums/media-buy-valid-action.json" } }, "available_actions": { "type": "array", "description": "Structured per-buy resolution of actions available immediately after creation. Authoritative — see `get-media-buys-response.json` for full semantics.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/media-buy-available-action.json" }, "uniqueItems": true }, "packages": { "type": "array", "description": "Array of created packages with complete state information", "items": { "$ref": "/schemas/3.1.0-rc.4/core/package.json" } }, "planned_delivery": { "$ref": "/schemas/3.1.0-rc.4/core/planned-delivery.json", "description": "The seller's interpreted delivery parameters. Describes what the seller will actually run -- geo, channels, flight dates, frequency caps, and budget. Present when the account has governance_agents or when the seller chooses to provide delivery transparency." }, "sandbox": { "type": "boolean", "description": "When true, this response contains simulated data from sandbox mode." }, "context": { "$ref": "/schemas/3.1.0-rc.4/core/context.json", "description": "Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST echo this object verbatim when the originating request carried context, including synchronous success, error, submitted, and webhook task-status payloads. Sellers MUST NOT parse this object for business logic." }, "ext": { "$ref": "/schemas/3.1.0-rc.4/core/ext.json" } }, "allOf": [ { "if": { "properties": { "confirmed_at": { "type": "null" } }, "required": ["confirmed_at"] }, "then": { "not": { "anyOf": [ { "properties": { "media_buy_status": { "const": "active" } }, "required": ["media_buy_status"] }, { "properties": { "status": { "const": "active" } }, "required": ["status"] } ] }, "properties": { "packages": { "items": { "not": { "required": ["committed_metrics"] } } } } } } ], "required": [ "media_buy_id", "confirmed_at", "revision", "packages" ], "additionalProperties": true, "not": { "required": [ "errors" ] } }, { "title": "CreateMediaBuyError", "description": "Error response - operation failed, no media buy created", "type": "object", "properties": { "errors": { "type": "array", "description": "Array of errors explaining why the operation failed", "items": { "$ref": "/schemas/3.1.0-rc.4/core/error.json" }, "minItems": 1 }, "context": { "$ref": "/schemas/3.1.0-rc.4/core/context.json", "description": "Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST echo this object verbatim when the originating request carried context, including synchronous success, error, submitted, and webhook task-status payloads. Sellers MUST NOT parse this object for business logic." }, "ext": { "$ref": "/schemas/3.1.0-rc.4/core/ext.json" } }, "required": [ "errors" ], "additionalProperties": true, "not": { "anyOf": [ { "required": [ "media_buy_id" ] }, { "required": [ "packages" ] }, { "required": [ "sandbox" ] }, { "properties": { "status": { "const": "submitted" } }, "required": [ "status" ] } ] } }, { "title": "CreateMediaBuySubmitted", "description": "Async task envelope returned when the media buy cannot be confirmed before the response is emitted — for example, when a guaranteed buy requires IO signing, when governance review is outstanding, or when the seller has queued the request for batch processing. The buyer polls tasks/get with task_id or receives a webhook when the task completes; the media_buy_id and packages land on the completion artifact, not this envelope. Do not use a 'pending_approval' MediaBuy.status for this case — that value is not in MediaBuyStatus; IO review and similar pre-issuance workflows are modeled at the task layer only.", "type": "object", "properties": { "status": { "type": "string", "const": "submitted", "description": "Task-level status literal. Discriminates this async envelope from the synchronous success shape, which uses `media_buy_status` for lifecycle state and only permits deprecated top-level MediaBuyStatus values during the 3.1 migration window. See task-status.json for the full task-status enum." }, "task_id": { "type": "string", "description": "Task handle the buyer uses with tasks/get, and that the seller references on push-notification callbacks. The media_buy_id is issued on the completion artifact, not here. Per AdCP wire conventions this is snake_case; A2A adapters MAY surface it as taskId, but the payload field emitted by the agent is task_id.", "x-entity": "task" }, "message": { "type": "string", "maxLength": 2000, "description": "Optional human-readable explanation of why the task is submitted — e.g., 'Awaiting IO signature from sales team; typical turnaround 2–4 hours.' Plain text only. Buyers MUST treat this as untrusted seller input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile seller may inject prompt-injection payloads aimed at the buyer's agent." }, "errors": { "type": "array", "description": "Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories, governance observations). Terminal failures belong in the error branch, not here.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/error.json" } }, "context": { "$ref": "/schemas/3.1.0-rc.4/core/context.json", "description": "Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST echo this object verbatim when the originating request carried context, including synchronous success, error, submitted, and webhook task-status payloads. Sellers MUST NOT parse this object for business logic." }, "ext": { "$ref": "/schemas/3.1.0-rc.4/core/ext.json" } }, "required": [ "status", "task_id" ], "additionalProperties": true, "not": { "anyOf": [ { "required": [ "media_buy_id" ] }, { "required": [ "packages" ] } ] } } ], "properties": {} }