Skip to main content
POST /api/v2/buyer/discovery/discover-products Fans a brief out to every reachable sales agent and returns grouped products, summary stats, budget context, and any seller proposals. If you omit discoveryId, a new session is created and its ID is returned. Pass an existing discoveryId to re-run or refine in place. This first call does the heavy work (LLM enrichment + agent fan-out); use Browse products to page the cached result cheaply.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/discovery/discover-products \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": 12345,
    "brief": "Premium CTV inventory for a Q3 sports launch — adults 25-54, US only, video creative",
    "budget": 250000,
    "channels": ["ctv", "olv"],
    "countries": ["US"],
    "flightDates": { "startDate": "2026-07-01T00:00:00Z", "endDate": "2026-09-30T23:59:59Z" },
    "groupLimit": 10,
    "productsPerGroup": 10
  }'

​
Parameters

FieldTypeRequiredNotes
advertiserIdintegerYesResolves the brand reference used to score agent results
discoveryIdstringNoReuse an existing session. Required when sending refine
campaignIdstringNoSeed brief, flight dates, and budget from a campaign; inline values override
proposalCodestringNoStorefront-issued code (e.g. PRP-XK4A29). Short-circuits discovery and returns the seller’s saved snapshot; other filters are ignored
briefstringNoNatural-language search context (max 5000 chars)
budgetnumberNoTotal budget in account currency; drives budget context and proposals
channelsstring[]Nodisplay, olv, ctv, social, or video (alias for olv). Default ["display","olv","ctv","social"]
countriesstring[]NoISO 3166-1 alpha-2 codes. Defaults to brand agent countries
flightDatesobjectNo{ startDate, endDate }, ISO 8601 datetimes; filters by agent availability
publisherDomainstringNoFilter to a single publisher domain
pricingModelenumNocpm, vcpm, cpc, cpcv, cpv, cpp, or flat_rate
storefrontIdsinteger[]NoRestrict to specific storefronts (max 50). OR-combined with storefrontNames
storefrontNamesstring[]NoRestrict by case-insensitive name substring (max 50)
groupLimitintegerNoMax product groups per page (max 10). Default 10
productsPerGroupintegerNoMax products per group (max 15). Default 10
groupOffset / productOffsetintegerNoPagination cursors. Default 0
debugbooleanNoInclude per-agent ADCP debug logs for failed agents
refinearrayNoRefinement directives (1–100). Requires discoveryId

​
Response

{
  "discoveryId": "disc_01HZX3YQ7K9R6V3M2P1E0F8B2T",
  "productGroups": [
    {
      "groupId": "ctx_disc_01HZX3-group-0",
      "groupName": "Acme Media Connected TV",
      "productCount": 4,
      "totalProducts": 12,
      "hasMoreProducts": true,
      "products": [
        {
          "productId": "prod_acme_ctv_sports",
          "name": "Acme Media Sports CTV - 30s",
          "channel": "ctv",
          "cpm": 32.5,
          "salesAgentId": "agent_acme_media",
          "deliveryType": "guaranteed",
          "pricingOptions": [
            { "pricingOptionId": "po_fixed_30", "pricingModel": "cpm", "isFixed": true, "fixedPrice": 32.5, "currency": "USD" }
          ]
        }
      ]
    }
  ],
  "totalGroups": 18,
  "hasMoreGroups": true,
  "summary": { "totalProducts": 142, "publishersCount": 18, "priceRange": { "min": 4.5, "max": 78.0, "avg": 21.4 } },
  "budgetContext": { "sessionBudget": 250000, "allocatedBudget": 0, "remainingBudget": 250000 },
  "proposals": [
    {
      "proposalId": "proposal_acme_q3_sports",
      "name": "Q3 Sports - premium CTV mix",
      "allocations": [
        { "productId": "prod_acme_ctv_sports", "allocationPercentage": 60 },
        { "productId": "prod_acme_olv_sports", "allocationPercentage": 40 }
      ],
      "totalBudgetGuidance": { "min": 150000, "recommended": 250000, "max": 400000, "currency": "USD" }
    }
  ]
}
Persist the returned discoveryId — every subsequent operation references it. When you send refine, the seller’s per-instruction reply comes back under refinementApplied matched by position, each with status of applied, partial, or unable.

​
Errors

  • 400 VALIDATION_ERROR — missing advertiserId, refine sent without discoveryId, or malformed flightDates.
  • 404 NOT_FOUND — advertiserId or campaignId not visible to the authenticated customer.
See Errors for the full error contract.

Discovery overview

Sessions, refinement, proposals, and storefronts

Browse products

Page the cached result without a re-run

Add products

Build a selection from discovered products

Apply proposal

Accept a seller’s full allocation