> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Get media buy > Get a single media buy with its why-visibility fields: pendingReason (why it is not delivering yet and since when), buyer-safe errorCode with ownership, the sanitized source message, forwardedAt, and the buyerReference support handle. One call answers "why is my buy stuck". Use GET /campaigns/{campaignId} for packages, products, and delivery. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /media-buys/{mediaBuyId} openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.apostra.com/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.apostra.com/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /media-buys/{mediaBuyId}: get: tags: - Campaigns summary: Get media buy description: >- Get a single media buy with its why-visibility fields: pendingReason (why it is not delivering yet and since when), buyer-safe errorCode with ownership, the sanitized source message, forwardedAt, and the buyerReference support handle. One call answers "why is my buy stuck". Use GET /campaigns/{campaignId} for packages, products, and delivery. operationId: getMediaBuy parameters: - in: path name: mediaBuyId schema: type: string minLength: 1 description: Buyer media buy ID example: mb_ETBn4gJ9Wu required: true description: Buyer media buy ID responses: '200': description: Get media buy content: application/json: schema: $ref: '#/components/schemas/BuyerMediaBuyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Caller is not a buyer — the route is mounted behind the buyer role guard. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: BuyerMediaBuyResponse: type: object properties: mediaBuy: $ref: '#/components/schemas/BuyerMediaBuy' required: - mediaBuy additionalProperties: false description: Response containing a single media buy with why-visibility ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response BuyerMediaBuy: type: object properties: mediaBuyId: type: string description: Buyer media buy ID example: mb_ETBn4gJ9Wu name: type: string description: Media buy name channelGroup: description: >- Campaign channel group that compiled into this media buy. Absent for legacy and ungrouped buys. type: object properties: channelGroupId: type: string name: type: string required: - channelGroupId - name additionalProperties: false campaignId: description: >- The campaign this media buy belongs to. Use it with get_campaign (optionally narrowed with ?mediaBuyId=) to read packages, products, and delivery for this buy. example: cmp_ETBn4gJ9Wu type: string status: type: string description: >- Apostra media buy status (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, ENDING, COMPLETED, CANCELED, FAILED, REJECTED). example: PENDING_APPROVAL archivedAt: description: >- When this media buy was archived (ISO 8601). Archiving controls visibility and preserves the media buy status. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ pendingAt: description: >- Which layer the buy is parked at; only present while status is PENDING_APPROVAL. Use pendingReason for the specific wait. type: string enum: - storefront - salesagent - unknown reconciliation: description: >- Additive operator-attention marker for a seller task whose local recovery deadline elapsed without terminal seller evidence. The buy remains non-terminal and its commitment remains held. Refresh the status or obtain confirmed seller cancellation/terminal evidence to resolve it. type: object properties: required: type: boolean enum: - true since: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ reason: type: string required: - required - since - reason additionalProperties: false pendingChange: description: >- A submitted change that has not yet reached the delivering buy. Every other field on this object describes what is LIVE, so this is the only place a queued change surfaces. Absent when there is nothing pending. allOf: - $ref: '#/components/schemas/MediaBuyPendingChange' pendingReason: description: >- Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: >- When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ errorCode: description: >- Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: >- Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: >- Buyer-safe detail from the source, reviewer, or storefront forwarder, when available. The value is whitespace-collapsed, truncated, and stripped of known upstream identifiers. type: string forwardedAt: description: >- When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ buyerReference: description: >- Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Apostra Support. example: sf:42:sf_mb_1783031864469_8pbc8mmr type: string startTime: description: 'When this media buy starts: "asap" or an ISO 8601 date-time.' type: string endTime: description: When this media buy ends (ISO 8601). type: string optimizationGoals: description: >- Optimization goals applied to this media buy and its packages. Absent when no goals are configured. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - viewable_rate - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach standard: anyOf: - type: string enum: - mrc - type: string enum: - groupm vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: {} additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: type: object properties: min: type: integer minimum: 1 maximum: 9007199254740991 max: type: integer minimum: 1 maximum: 9007199254740991 window: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} required: - window additionalProperties: {} view_duration_seconds: type: number minimum: 0 exclusiveMinimum: true target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} priority: type: integer minimum: 1 maximum: 9007199254740991 required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string minLength: 1 event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: integer minimum: 1 maximum: 9007199254740991 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: {} additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: {} priority: type: integer minimum: 1 maximum: 9007199254740991 required: - kind - vendor - metric_id additionalProperties: {} goalCommitment: description: >- What the seller committed to for your goal when this buy was booked: the commitment kind (guaranteed, best_effort, report_only), the goal asked, the target the seller's terms commit or aim at, whether every product meets your asked target by its kind (a cost at or under it, a rate or return at or above it), one answer per product, and the proposal version it came from. Absent on buys booked before commitments were recorded. allOf: - $ref: '#/components/schemas/MediaBuyGoalCommitment' frequencyCap: description: >- Media-buy-wide frequency cap requested from the seller and whether the exact cap has been confirmed by its acceptance response. type: object properties: level: type: string enum: - mediaBuy description: Counter scope. requested: type: object properties: maxImpressions: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Maximum impressions allowed in the window. per: type: string enum: - individuals - households - devices - accounts - cookies - custom description: Reach unit counted by the seller. window: type: object properties: interval: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Positive whole-number window length. unit: type: string enum: - seconds - minutes - hours - days - campaign description: Window unit. required: - interval - unit additionalProperties: false description: Counting window for the cap. required: - maxImpressions - per - window additionalProperties: false description: Seller-enforced AdCP 3.2 cap configuration. effective: description: Exact cap echoed by the seller after acceptance. type: object properties: maxImpressions: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Maximum impressions allowed in the window. per: type: string enum: - individuals - households - devices - accounts - cookies - custom description: Reach unit counted by the seller. window: type: object properties: interval: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Positive whole-number window length. unit: type: string enum: - seconds - minutes - hours - days - campaign description: Window unit. required: - interval - unit additionalProperties: false description: Counting window for the cap. required: - maxImpressions - per - window additionalProperties: false status: type: string enum: - requested - confirmed description: >- Requested until the seller returns the exact cap; confirmed afterwards. required: - level - requested - status additionalProperties: false pausedBy: nullable: true description: >- Who paused this media buy: 'buyer' for a direct per-buy pause, 'campaign' for a campaign-cascade pause. Absent or null when the buy is not currently paused or was paused before provenance tracking. type: string enum: - buyer - campaign pauseRequestedAt: nullable: true description: >- When a pause the seller accepted but has not applied was requested. The buy stays ACTIVE until it applies. Null otherwise. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was created (ISO 8601) updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was last updated (ISO 8601) required: - mediaBuyId - name - status - createdAt - updatedAt additionalProperties: false description: >- A single media buy with its optimization goals and why-visibility annotation (pendingReason, errorCode, forwardedAt, buyerReference). Use get_campaign for packages, products, and delivery. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object MediaBuyPendingChange: type: object properties: status: type: string description: >- Lifecycle status of the pending change itself, typically PENDING_APPROVAL. This is NOT the status of the buy: the buy keeps its own top-level status, which reflects what is delivering now. example: PENDING_APPROVAL pendingAt: description: >- Which layer the pending change is parked at. 'storefront' = waiting on the storefront operator's manual approval, 'salesagent' = the inventory source is still processing it, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown reason: description: >- Reason recorded when the change was submitted, when one was supplied. example: Extended to 8/11 with W5+W6 gross budget type: string proposalId: description: >- ID of the pending update proposal awaiting seller approval, present when the change is routed through the async approval flow. Pass to DELETE /api/v2/buyer/update-proposals/{proposalId} to cancel it. example: uprop_abc1234567 type: string differences: type: object properties: endTime: description: Flight end date change (ISO 8601). type: object properties: live: description: The value currently in effect on the delivering buy. type: string proposed: description: The value the pending change would set. type: string additionalProperties: false budget: description: >- Total budget change in the buy's currency, summed across its packages. type: object properties: live: description: The value currently in effect on the delivering buy. type: number proposed: description: The value the pending change would set. type: number additionalProperties: false creatives: description: >- Creative IDs currently attached compared with the proposed attachment set. type: object properties: live: description: The value currently in effect on the delivering buy. type: array items: type: string proposed: description: The value the pending change would set. type: array items: type: string additionalProperties: false additionalProperties: false description: >- Only the fields whose pending value differs from live appear here. An empty object means a pending change exists whose comparable fields already match live. required: - status - differences additionalProperties: false description: >- A buyer-submitted change that has been accepted by Apostra but has NOT yet taken effect on the delivering buy. Its presence is the signal that this buy has an unapplied change; absence means everything reported is live. Never treat these values as delivering. MediaBuyPendingReason: type: string enum: - forward_failed_needs_correction - forward_failed_retrying - awaiting_storefront_approval - awaiting_source_moderation - no_creatives_attached - source_rejected_creatives - creative_processing_at_source - awaiting_creative_approval - accepted_awaiting_trafficking - scheduled_not_started description: >- Why a not-yet-delivering media buy is waiting, and implicitly whose side owns the wait. A platform-derived annotation — never a status value. awaiting_storefront_approval / awaiting_source_moderation / creative_processing_at_source / awaiting_creative_approval = the seller side owns the wait; no_creatives_attached / source_rejected_creatives = the buyer owns it (attach or fix creatives); forward_failed_retrying / forward_failed_needs_correction = the platform owns it; accepted_awaiting_trafficking / scheduled_not_started = nothing is wrong, the buy is queued or scheduled. BuyerMediaBuyErrorCode: type: string enum: - product_no_longer_available - source_rejected - storefront_rejected - source_unavailable - source_configuration_error - product_configuration_error - invalid_request - quote_expired - platform_error description: >- Buyer-safe structured error code for a media buy that failed to forward or was rejected. Paired with errorOwner (who owns the fix) and, when the source provided one, a sanitized human-readable message. MediaBuyErrorOwner: type: string enum: - buyer_input - platform - seller description: >- Which party owns fixing the error: buyer_input (the request needs a correction from the buyer), platform (Apostra owns the fault), seller (the storefront or its source made the decision or is unavailable). MediaBuyGoalCommitment: type: object properties: source: type: string enum: - proposal - campaign description: >- Where the answers came from: 'proposal' when at least one product on the buy keeps the accepted proposal version's answer, 'campaign' when every answer was derived from the campaign's goals and the products' own terms. proposalVersionId: description: >- The accepted proposal version the buy was booked from, whenever there was one. Present even when source reads 'campaign' because none of the buy's products matched that version's answers, so the booking's provenance is never lost. type: string kind: type: string enum: - guaranteed - best_effort - report_only askedGoal: nullable: true type: object properties: kind: type: string enum: - metric - event subject: type: string eventTypes: type: array items: type: string target: nullable: true anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false description: >- A goal target, judged by its kind: cost_per (a cost per unit, met at or under the value; per thousand for CPM pricing), threshold_rate (a minimum rate per impression, met at or above), per_ad_spend (a minimum return on ad spend, met at or above), or maximize_value (no number to meet). required: - kind - subject - eventTypes - target additionalProperties: false answeredTarget: nullable: true description: >- The target the products' terms commit or aim at for the asked goal, of the same kind as the ask when they answer it: the worst across products, meaning the highest cost_per, the lowest threshold_rate, or the lowest per_ad_spend. maximize_value carries no number. anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false meetsAskedTarget: nullable: true description: >- Whether every product answers the asked target, judged by kind: a cost_per is met at or under the ask, a threshold_rate or per_ad_spend at or above it. false when any product misses it or did not answer with the same kind. null when the goal carries no target or a maximize_value target, which has no number to meet. type: boolean goalAnswers: type: array items: type: object properties: productId: type: string storefrontId: description: >- The Storefront the answered line resolves to, fixed when the answer was booked so a later refresh keeps it for exactly that Storefront's line. Present on every booked answer whose line resolved to a Storefront, campaign-derived or copied from an accepted proposal alike. nullable: true type: string pricingOptionId: nullable: true type: string pricingModel: nullable: true type: string fixedPrice: nullable: true type: number currency: nullable: true type: string deliveryType: nullable: true type: string enum: - guaranteed - non_guaranteed measurementTerms: nullable: true sellerOptimizationGoals: nullable: true type: array items: {} askedGoal: nullable: true type: object properties: kind: type: string enum: - metric - event subject: type: string eventTypes: type: array items: type: string target: nullable: true anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false description: >- A goal target, judged by its kind: cost_per (a cost per unit, met at or under the value; per thousand for CPM pricing), threshold_rate (a minimum rate per impression, met at or above), per_ad_spend (a minimum return on ad spend, met at or above), or maximize_value (no number to meet). required: - kind - subject - eventTypes - target additionalProperties: false answeredTarget: nullable: true anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false description: >- A goal target, judged by its kind: cost_per (a cost per unit, met at or under the value; per thousand for CPM pricing), threshold_rate (a minimum rate per impression, met at or above), per_ad_spend (a minimum return on ad spend, met at or above), or maximize_value (no number to meet). commitment: type: string enum: - guaranteed - best_effort - report_only required: - productId - pricingOptionId - pricingModel - fixedPrice - currency - deliveryType - measurementTerms - sellerOptimizationGoals - askedGoal - answeredTarget - commitment additionalProperties: false description: >- One answer per product on the buy: the product the accepted proposal answered keeps that answer, any other product is answered from its own terms. required: - source - kind - askedGoal - answeredTarget - meetsAskedTarget - goalAnswers additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.