Skip to main content
POST
/
discovery
/
discover-products
Discover products
curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/discovery/discover-products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "advertiserId": 12345
}
'
{
  "discoveryId": "abc123-def456-ghi789",
  "productGroups": [
    {
      "groupId": "<string>",
      "groupName": "<string>",
      "products": [
        {
          "productId": "prod_123",
          "name": "Premium CTV Inventory - Sports",
          "channel": "ctv",
          "formatTypes": [
            "video",
            "15s",
            "30s"
          ],
          "cpm": 12.5,
          "salesAgentId": "<string>",
          "salesAgentName": "<string>",
          "description": "<string>",
          "deliveryType": "guaranteed",
          "briefRelevance": "<string>",
          "productCard": {
            "formatId": {
              "agentUrl": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "productCardDetailed": {
            "formatId": {
              "agentUrl": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "pricingOptions": [
            {
              "pricingOptionId": "<string>",
              "pricingModel": "<string>",
              "isFixed": true,
              "rate": 123,
              "floorPrice": 123,
              "fixedPrice": 123,
              "currency": "<string>"
            }
          ],
          "estimatedExposures": 0,
          "forecast": {},
          "publisherProperties": [
            {
              "publisherDomain": "<string>",
              "propertyType": "<string>",
              "name": "<string>",
              "selectionType": "<string>",
              "identifiers": [
                {}
              ]
            }
          ],
          "isSandbox": true
        }
      ],
      "productCount": 4503599627370495,
      "totalProducts": 4503599627370495,
      "hasMoreProducts": true,
      "description": "<string>"
    }
  ],
  "totalGroups": 25,
  "hasMoreGroups": true,
  "summary": {
    "totalProducts": 150,
    "publishersCount": 25,
    "priceRange": {
      "min": 123,
      "max": 123,
      "avg": 123
    }
  },
  "budgetContext": {
    "sessionBudget": 123,
    "allocatedBudget": 123,
    "remainingBudget": 123,
    "budgetWarning": "<string>"
  },
  "proposals": [
    {
      "proposalId": "<string>",
      "name": "<string>",
      "allocations": [
        {
          "productId": "<string>",
          "allocationPercentage": 50,
          "pricingOptionId": "<string>",
          "rationale": "<string>",
          "sequence": 0,
          "tags": [
            "<string>"
          ]
        }
      ],
      "description": "<string>",
      "briefAlignment": "<string>",
      "salesAgentId": "<string>",
      "salesAgentName": "<string>",
      "expiresAt": "<string>",
      "totalBudgetGuidance": {
        "min": 123,
        "recommended": 123,
        "max": 123,
        "currency": "<string>"
      }
    }
  ],
  "agentResults": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "success": true,
      "productCount": 4503599627370495,
      "error": "<string>",
      "skipReason": "<string>",
      "rawResponseData": "<unknown>",
      "debugLogs": [
        {
          "timestamp": "<string>",
          "type": "<string>",
          "message": "<string>",
          "request": {},
          "response": {}
        }
      ]
    }
  ],
  "refinementApplied": [
    {
      "status": "applied",
      "scope": "request",
      "id": "<string>",
      "notes": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.interchange.io/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for discovering products with optional auto-session creation

​
advertiserId
integer
required

Advertiser ID to resolve brand manifest

Required range: x <= 9007199254740991
Example:

12345

​
discoveryId
string

Existing discovery ID. If not provided, a new discovery session is created.

Example:

"abc123-def456-ghi789"

​
campaignId
string

Campaign ID to seed discovery from. The campaign brief, flight dates, and budget are used as defaults (explicit request values take precedence).

Example:

"campaign_ea5e33dd-d65b-44c7-a3e8-8e1db1d137b4"

​
channels
enum<string>[]

Channels to search (defaults to ["display", "olv", "ctv", "social"]). "video" is accepted as an alias for "olv".

Available options:
display,
olv,
ctv,
social,
video
Example:
["ctv", "display"]
​
countries
string[]

Countries to target (defaults to brand agent countries if not specified)

Maximum array length: 250
Pattern: ^[A-Z]{2}$
Example:
["US", "CA"]
​
brief
string

Natural language context for product search

Maximum string length: 5000
Example:

"Looking for premium video inventory targeting tech enthusiasts"

​
budget
number

Budget for the discovery

Required range: x > 0
Example:

50000

​
flightDates
object

Optional flight dates for availability filtering

​
publisherDomain
string

Filter products by publisher domain (exact domain component match)

Minimum string length: 1
Example:

"hulu"

​
pricingModel
enum<string>

Filter products by pricing model

Available options:
cpm,
vcpm,
cpc,
cpcv,
cpv,
cpp,
flat_rate
Example:

"cpm"

​
storefrontIds
integer[]

Filter discovery to these storefronts. Highly encouraged when the buyer wants results scoped to specific sellers — pass the IDs returned by list_storefronts. Combined with storefrontNames using OR logic. An empty array or omitted field both mean "no request-level filter" — if a campaignId is also provided and the campaign was created with storefrontIds, the campaign-level value is used in that case.

Maximum array length: 50
Required range: x <= 9007199254740991
Example:
[42, 57]
​
storefrontNames
string[]

Filter discovery to storefronts whose name matches one of these values (case-insensitive substring match). Use when the buyer mentions a seller by name. Combined with storefrontIds using OR logic. An empty array or omitted field both mean "no request-level filter" — campaign-level pinning is used in that case if available.

Maximum array length: 50
Maximum string length: 255
Example:
["Acme", "Acme Exchange"]
​
groupLimit
integer
default:10

Maximum number of product groups to return (default: 10, max: 10)

Required range: x <= 10
Example:

10

​
groupOffset
integer
default:0

Number of groups to skip for pagination

Required range: 0 <= x <= 9007199254740991
Example:

0

​
productsPerGroup
integer
default:10

Maximum products to return per group (default: 10, max: 15)

Required range: x <= 15
Example:

10

​
productOffset
integer
default:0

Number of products to skip within each group (default: 0, max: 1000)

Required range: 0 <= x <= 1000
Example:

5

​
debug
boolean

When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting

​
refine
object[]

Refinement instructions for iterating on previous discovery results. When provided, discoveryId is required.

Required array length: 1 - 100 elements

A refinement instruction for iterating on discovery results. Scoped to the overall request, a specific product, or a specific proposal.

Response

Discover products

Response from discovering products

​
discoveryId
string
required

Discovery ID

Example:

"abc123-def456-ghi789"

​
productGroups
object[]
required

Products grouped by publisher

​
totalGroups
integer
required

Total number of product groups available

Required range: 0 <= x <= 9007199254740991
Example:

25

​
hasMoreGroups
boolean
required

Whether more groups are available beyond those shown

​
summary
object
required

Summary statistics for discovered products

​
budgetContext
object

Budget context if budget was provided

​
proposals
object[]

Recommended media plans from sales agents (ADCP v3). Each proposal explains WHY certain products are recommended together and how budget should be allocated.

​
agentResults
object[]

Debug info for failed agents only. Only present when debug=true and at least one agent failed.

​
refinementApplied
object[]

Seller's response to each refinement instruction, matched by position to the request's refine array. Only present when refine was provided.