> ## 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. # Auto-select products > Automatically select products for a performance campaign using a 3-tier strategy (scoring → measurability → CPM heuristic). Campaign must be in DRAFT status. Supports iterative refinement via ADCP-style refine directives — review results then re-call with include/omit/more_like_this to adjust selections. Replaces all previously selected products. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml post /campaigns/{campaignId}/auto-select-products 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: /campaigns/{campaignId}/auto-select-products: post: tags: - Campaigns summary: Auto-select products description: >- Automatically select products for a performance campaign using a 3-tier strategy (scoring → measurability → CPM heuristic). Campaign must be in DRAFT status. Supports iterative refinement via ADCP-style refine directives — review results then re-call with include/omit/more_like_this to adjust selections. Replaces all previously selected products. operationId: autoSelectProducts parameters: - in: path name: id schema: type: string minLength: 1 description: Unique identifier for the campaign example: cmp_987654321 required: true description: Unique identifier for the campaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutoSelectProductsRequest' responses: '200': description: Auto-select products content: application/json: schema: $ref: '#/components/schemas/AutoSelectProductsResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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: AutoSelectProductsRequest: type: object properties: refine: description: >- Array of refinement directives from a previous auto-select response. Supports request-scoped direction and product-scoped include/omit/more_like_this actions. minItems: 1 type: array items: $ref: '#/components/schemas/RefinementItem' maxProducts: description: Maximum number of products to select example: 5 type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 minBudgetPerProduct: description: Minimum budget to allocate per product example: 500 type: number minimum: 0 exclusiveMinimum: true additionalProperties: false description: >- Optional refinement parameters for iterative auto-select product selection. Based on ADCP refine spec. AutoSelectProductsResponse: type: object properties: campaignId: type: string description: Campaign ID discoveryId: type: string description: Discovery session ID containing the selected products selectedProducts: type: array items: type: object properties: productId: type: string name: type: string salesAgentId: type: string groupId: type: string groupName: type: string cpm: type: number budget: type: number pricingOptionId: type: string goalCoverage: description: >- Which of the campaign's optimization goals the product cannot optimize to. Absent when the campaign has no goals or the platform holds no copy of the product. Auto-select ranks products that can optimize to the primary goal ahead of products that cannot. allOf: - $ref: '#/components/schemas/OptimizationGoalCoverage' required: - productId - name - salesAgentId - groupId - groupName - budget additionalProperties: false description: Products selected and added to the discovery session budgetContext: type: object properties: campaignBudget: type: number totalAllocated: type: number remainingBudget: type: number currency: type: string required: - campaignBudget - totalAllocated - remainingBudget - currency additionalProperties: false description: Budget allocation summary productCount: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of products selected previouslySelectedCount: description: >- Number of previously selected products that were replaced by auto-select type: integer minimum: 0 maximum: 9007199254740991 required: - campaignId - discoveryId - selectedProducts - budgetContext - productCount additionalProperties: false description: Response from auto-selecting products for a performance campaign 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 RefinementItem: oneOf: - type: object properties: scope: type: string enum: - request description: Applies direction to the overall selection ask: type: string minLength: 1 description: >- Free-text direction for the overall selection, e.g. "more video options and less display" required: - scope - ask description: 'Request-scoped refinement: direction for the overall selection' - type: object properties: scope: type: string enum: - product description: Targets a specific product from a prior auto-select response id: type: string minLength: 1 description: Product ID from a prior auto-select response action: type: string enum: - include - omit - moreLikeThis description: >- include: keep this product; omit: exclude it; moreLikeThis: find similar products ask: description: Optional direction when action is include or more_like_this type: string minLength: 1 required: - scope - id - action description: 'Product-scoped refinement: target a specific product' description: A single refinement directive (request-scoped or product-scoped) type: object OptimizationGoalCoverage: type: object properties: coversPrimaryGoal: type: boolean description: >- Whether the product can optimize to the primary goal (priority 1, else the first goal). uncovered: type: array items: type: object properties: code: $ref: '#/components/schemas/DroppedOptimizationGoalCode' reason: type: string description: Why the goal was not sent on this package goal: 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: {} description: The AdCP optimization goal the product cannot take required: - code - reason - goal additionalProperties: false description: >- Goals the product cannot optimize to, in goal order. Empty when it can optimize to every goal. expected: description: >- The primary goal's expected rate from the product's forecast against the rate the goal requires. Absent when the goal has no target, is not a views, viewable_rate or completed_views goal, or the forecast carries no range for it. allOf: - $ref: '#/components/schemas/ExpectedGoalPerformance' required: - coversPrimaryGoal - uncovered additionalProperties: false description: >- Whether the product can optimize to the campaign's optimization goals, read from its AdCP optimization declaration 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 DroppedOptimizationGoalCode: type: string enum: - goal_kind_not_declared - metric_not_declared - target_kind_not_declared - reach_unit_not_declared - view_duration_not_declared - viewability_standard_not_declared - vendor_metric_not_declared - over_max_optimization_goals description: >- Why the goal was not sent: the product's AdCP optimization declaration (metric_optimization, conversion_tracking, vendor_metric_optimization) does not cover the goal's kind, metric, target kind, reach unit, view duration, viewability standard or vendor metric, or the product's max_optimization_goals was reached. ExpectedGoalPerformance: type: object properties: basis: type: string enum: - viewable_rate - viewable_per_impression - completion_rate low: type: number mid: type: number high: type: number required: type: number verdict: type: string enum: - likely - possible - unlikely required: - basis - low - mid - high - required - verdict additionalProperties: false description: >- Forecast rate vs rate needed: likely if low meets it, possible if high does 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.