Skip to main content
POST
/
discovery
/
discover-products
Discover products
curl --request POST \
  --url https://api.agentic.scope3.com/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",
          "publisher": "ESPN",
          "channel": "ctv",
          "formatTypes": [
            "video",
            "15s",
            "30s"
          ],
          "cpm": 12.5,
          "salesAgentId": "<string>",
          "salesAgentName": "<string>",
          "description": "<string>",
          "deliveryType": "guaranteed",
          "briefRelevance": "<string>",
          "productCard": {
            "format_id": {
              "agent_url": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "productCardDetailed": {
            "format_id": {
              "agent_url": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "pricingOptions": [
            {
              "pricing_option_id": "<string>",
              "pricing_model": "<string>",
              "is_fixed": true,
              "rate": 123,
              "floor_price": 123,
              "fixed_price": 123,
              "currency": "<string>"
            }
          ],
          "estimatedExposures": 0,
          "forecast": {}
        }
      ],
      "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>"
      }
    }
  ]
}

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"

​
salesAgentIds
string[]

Filter products by sales agent ID(s)

Maximum array length: 50
Maximum string length: 255
Example:
["agent_456"]
​
salesAgentNames
string[]

Filter products by sales agent name(s) (case-insensitive substring match)

Maximum array length: 50
Maximum string length: 255
Example:
["Acme Ad 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

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.