Skip to main content
GET
/
discovery
/
{discoveryId}
/
discover-products
Browse products for discovery session
curl --request GET \
  --url https://api.interchange.io/api/v2/buyer/discovery/{discoveryId}/discover-products \
  --header 'Authorization: Bearer <token>'
{
  "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

Path Parameters

​
discoveryId
string
required

Discovery ID

Minimum string length: 1
Example:

"abc123-def456-ghi789"

Query Parameters

​
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

​
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

Filter products by storefront ID(s) (from list_storefronts).

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

Filter products by storefront name (case-insensitive substring match).

Maximum array length: 50
Maximum string length: 255
Example:
["Acme", "Acme Exchange"]
​
debug

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

Response

Browse products for discovery session

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.