The API is in active development — breaking changes may occur before final release.

Buyer API Reference

Overview

The Scope3 Buyer API provides enhanced capabilities for brand advertisers to manage advertising campaigns through both REST and MCP (Model Context Protocol) interfaces. The API follows the SESOFI (Single Entity, Single Operation, Full Information) design principle:

Single Entity - Each endpoint manages one resource type
Single Operation - One call does one thing completely
Full Information - GET returns everything, PUT/POST accepts everything

Connection Methods

REST API
MCP (AI Agents)

REST API (Recommended for traditional integrations)

Standard HTTP methods with JSON request/response bodies.Production:

https://api.agentic.scope3.com/api/buyer

Staging:

https://api.agentic.staging.scope3.com/api/buyer

Example:

curl https://api.agentic.scope3.com/api/buyer/advertisers \
  -H "Authorization: Bearer scope3_your_api_key_here"

MCP (Model Context Protocol) for AI Agents

JSON-RPC 2.0 over HTTP POST with session management.Production:

https://api.agentic.scope3.com/mcp/buyer

Staging:

https://api.agentic.staging.scope3.com/mcp/buyer

Example:

curl -X POST https://api.agentic.scope3.com/mcp/buyer \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: your-uuid" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

Production: /api/buyer/openapi.yaml
Staging: /api/buyer/openapi.yaml

Authentication

All API requests require authentication using your Scope3 API key:

Authorization: Bearer scope3_your_api_key_here

Get API Key

Request API credentials to get started

REST API Endpoints

Advertisers

Core advertiser management endpoints. Following SESOFI, GET returns full advertiser data including all nested configuration.

Method	Endpoint	Description
GET	`/api/buyer/advertisers`	List all advertisers
POST	`/api/buyer/advertisers`	Create a new advertiser
GET	`/api/buyer/advertisers/:id`	Get advertiser with full configuration
PUT	`/api/buyer/advertisers/:id`	Update advertiser (partial or full)

Query Parameters for GET /advertisers:

includeAccounts - When true, includes linked partner accounts in each advertiser response (avoids N+1 calls to /accounts)
includeBrand - When true, includes resolved brand information (logos, colors, industry)
take / skip - Pagination

Example - List Advertisers with Accounts:

curl "https://api.agentic.scope3.com/api/buyer/advertisers?includeAccounts=true" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example - Get Advertiser (returns EVERYTHING):

curl https://api.agentic.scope3.com/api/buyer/advertisers/adv_123 \
  -H "Authorization: Bearer scope3_your_api_key_here"

Response includes:

Advertiser details (name, industry, etc.)
All conversion events
All test cohorts
Measurement configuration
Brand associations

Example - Create Advertiser with Linked Accounts:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand": { "domain": "acme.com" },
    "linkedAccounts": [
      {
        "partnerId": "premiumvideo_a1b2c3d4",
        "accountId": "acc_acme_pinnacle",
        "billingType": "brand"
      }
    ]
  }'

linkedAccounts field (available on create and update):

partnerId - Partner agent ID
accountId - Partner-assigned account identifier
billingType - Billing arrangement type (e.g. "brand", "agency")

On update, existing linked accounts are not removed — only new ones are added.

Conversion Events

Manage conversion events for measuring campaign effectiveness.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/conversion-events`	List all conversion events
POST	`/api/buyer/advertisers/:advertiserId/conversion-events`	Create a conversion event
GET	`/api/buyer/advertisers/:advertiserId/conversion-events/:id`	Get a specific conversion event
PUT	`/api/buyer/advertisers/:advertiserId/conversion-events/:id`	Update a conversion event
DELETE	`/api/buyer/advertisers/:advertiserId/conversion-events/:id`	Delete a conversion event

Example - Create Conversion Event:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/conversion-events \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchase Complete",
    "eventType": "purchase",
    "value": 50.00,
    "currency": "USD"
  }'

Test Cohorts

Manage test cohorts for A/B testing and incrementality measurement.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/test-cohorts`	List all test cohorts
POST	`/api/buyer/advertisers/:advertiserId/test-cohorts`	Create a test cohort
GET	`/api/buyer/advertisers/:advertiserId/test-cohorts/:id`	Get a specific test cohort
PUT	`/api/buyer/advertisers/:advertiserId/test-cohorts/:id`	Update a test cohort
DELETE	`/api/buyer/advertisers/:advertiserId/test-cohorts/:id`	Delete a test cohort

Example - Create Test Cohort:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/test-cohorts \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Holdout Test",
    "type": "holdout",
    "percentage": 10,
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }'

Measurement Config

Configure measurement settings for an advertiser. This is a singleton resource per advertiser.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/measurement-config`	Get measurement configuration
PUT	`/api/buyer/advertisers/:advertiserId/measurement-config`	Update measurement configuration

Example - Update Measurement Config:

curl -X PUT https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/measurement-config \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "attributionWindow": 30,
    "attributionModel": "lastTouch",
    "measurementEnabled": true,
    "crossDeviceTracking": true
  }'

Brands

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/brand`	Get brand for advertiser
POST	`/api/buyer/advertisers/:advertiserId/brand`	Create brand for advertiser
PUT	`/api/buyer/advertisers/:advertiserId/brand`	Update brand

Campaigns

Method	Endpoint	Description
GET	`/api/buyer/campaigns`	List all campaigns
POST	`/api/buyer/campaigns`	Create a new campaign
GET	`/api/buyer/campaigns/:id`	Get campaign details
PUT	`/api/buyer/campaigns/:id`	Update campaign
POST	`/api/buyer/campaigns/:id/execute`	Execute/launch campaign
POST	`/api/buyer/campaigns/:id/pause`	Pause campaign

Creative Sets

Manage creative sets containing assets (video, image, text) that can be combined into different creative formats with macro expansion support.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/creative-sets`	List all creative sets
POST	`/api/buyer/advertisers/:advertiserId/creative-sets`	Create a creative set
GET	`/api/buyer/advertisers/:advertiserId/creative-sets/:id`	Get a specific creative set
PUT	`/api/buyer/advertisers/:advertiserId/creative-sets/:id`	Update a creative set
DELETE	`/api/buyer/advertisers/:advertiserId/creative-sets/:id`	Delete a creative set
POST	`/api/buyer/advertisers/:advertiserId/creative-sets/:id/assets`	Add an asset to a creative set
DELETE	`/api/buyer/advertisers/:advertiserId/creative-sets/:id/assets/:assetId`	Remove an asset from a creative set

Asset Types:

video - Video files with duration, dimensions, codec metadata
image - Image files with dimensions and alt text
text - Text content for headlines, descriptions, CTAs

Creative Formats:

display_banner - Standard display banners
native - Native ad formats
video_instream - In-stream video ads
video_outstream - Out-stream video ads
audio - Audio ads
ctv - Connected TV ads
dooh - Digital out-of-home ads

Example - Create Creative Set:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/creative-sets \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer 2025 Campaign Creatives",
    "description": "Creative assets for summer promotional campaign",
    "assets": [
      {
        "type": "video",
        "name": "Hero Video 30s",
        "url": "https://storage.example.com/videos/hero-30s.mp4",
        "metadata": {
          "duration": 30,
          "width": 1920,
          "height": 1080
        }
      },
      {
        "type": "text",
        "name": "Primary Headline",
        "content": "Discover Amazing Savings Today!"
      }
    ],
    "tags": ["summer", "promotional", "2025"]
  }'

Media Buys

View media buy execution status and delivery metrics.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/media-buys`	List all media buys
GET	`/api/buyer/advertisers/:advertiserId/media-buys/:id`	Get a specific media buy

Media Buy Statuses:

DRAFT - Initial state, not yet submitted
PENDING_APPROVAL - Submitted, awaiting approval
INPUT_REQUIRED - Additional information needed
ACTIVE - Currently running
PAUSED - Temporarily paused
COMPLETED - Successfully finished
FAILED - Execution failed
REJECTED - Not approved
ARCHIVED - Archived/deleted

Example - List Media Buys:

curl https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/media-buys \
  -H "Authorization: Bearer scope3_your_api_key_here"

Reporting

Access reporting metrics and performance data for campaigns and media buys.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/reporting`	Get reporting

Query Parameters:

days - Number of days to include (default: 7, max: 90)
startDate - Start date in ISO format (YYYY-MM-DD)
endDate - End date in ISO format (YYYY-MM-DD)
campaignId - Filter by campaign ID
mediaBuyId - Filter by media buy ID

Example - Get Reporting:

curl "https://api.agentic.scope3.com/api/buyer/advertisers/adv_123/reporting?days=7" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Response:

{
  "dailyMetrics": [
    {
      "date": "2025-01-15",
      "impressions": 150000,
      "spend": 1250.50,
      "clicks": 450
    }
  ],
  "totals": {
    "impressions": 325000,
    "spend": 2701.25,
    "clicks": 970
  },
  "periodStart": "2025-01-15",
  "periodEnd": "2025-01-21"
}

Partner Accounts

Discover and link advertiser accounts on partner platforms (e.g. a DSP seat). The flow is: discover available accounts via GET .../accounts/available, then assign one to the advertiser via POST .../accounts.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/accounts/available`	List accounts discovered on a partner platform
GET	`/api/buyer/advertisers/:advertiserId/accounts`	List accounts linked to this advertiser
GET	`/api/buyer/advertisers/:advertiserId/accounts/:accountId`	Get a single linked account
POST	`/api/buyer/advertisers/:advertiserId/accounts`	Assign a discovered account to this advertiser

Query Parameters for GET .../accounts/available:

partnerId (required) - Partner agent ID to discover accounts from
credentialId - ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this agent. Use GET /sales-agents/accountCredentials to list credentials and their IDs.
refresh - Set to true to re-fetch from the partner; defaults to cached results

Example - Discover available accounts:

curl "https://api.agentic.scope3.com/api/buyer/advertisers/12345/accounts/available?partnerId=premiumvideo_a1b2c3d4" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example - Assign an account:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/12345/accounts \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": "premiumvideo_a1b2c3d4",
    "accountId": "acc_acme_pinnacle"
  }'

Account fields (from partner):

accountId - Partner-assigned account identifier
name - Human-readable account name (e.g. "Acme c/o Pinnacle")
advertiser - Advertiser name as recorded by the partner
billingProxy - Agency or proxy buying on behalf of the advertiser
house - Domain or house identifier
billing - Billing arrangement type (e.g. "brand")

Partner Agents

Discover and configure partner ad platforms. Each agent exposes capabilities describing how it handles account resolution and billing.

Method	Endpoint	Description
GET	`/api/buyer/sales-agents`	List available partner agents
POST	`/api/buyer/sales-agents/:agentId/accounts`	Register an account on a partner agent

Query Parameters for GET /sales-agents:

supportsRegistration - "true" to return only agents that require operator authentication (requiresOperatorAuth = true)
limit / cursor - Pagination

Example - List Partner Agents:

curl "https://api.agentic.scope3.com/api/buyer/sales-agents?supportsRegistration=true" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Agent response fields:

requiresOperatorAuth (boolean) - When true, buyers must register their own credentials with this partner before transacting
billingOptions - Billing arrangements supported by this partner. null when capabilities have not been fetched yet.
- default - Default billing type (e.g. "brand")
- supported - Array of supported billing types (e.g. ["brand", "agency"])
accountResolution - How this agent resolves account references. null when capabilities have not been fetched yet.
- "explicit_account_id" - Accounts are discovered via list_accounts and referenced by their partner-assigned ID
- "implicit_from_sync" - Buyer declares brand/operator via sync_accounts and the seller provisions accounts

Example - Register an Account:

curl -X POST https://api.agentic.scope3.com/api/buyer/sales-agents/premiumvideo_a1b2c3d4/accounts \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIdentifier": "acme-brand-account",
    "accountType": "brand"
  }'

The advertiserId field has been removed from the register account body. Use the Partner Accounts endpoints to link accounts to specific advertisers after registration.

Catalogs

Manage product and offering catalogs that can be synced to partner platforms.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/catalogs`	List catalogs
POST	`/api/buyer/advertisers/:advertiserId/catalogs`	Create a catalog
GET	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Get a catalog
PUT	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Update a catalog
DELETE	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Archive a catalog (also archives all offerings)
POST	`/api/buyer/advertisers/:advertiserId/catalogs/sync`	Sync catalogs to partner platforms

Supported catalog types: product, offering, hotel, flight, destination, home_listing, vehicle, job, local, retail, travel, education Example - Create a catalog:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/12345/catalogs \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Products",
    "type": "product",
    "description": "Summer 2025 product catalog"
  }'

Example - Sync to partners:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/12345/catalogs/sync \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerIds": ["premiumvideo_a1b2c3d4"]
  }'

Offerings

Manage individual offerings (products, listings, etc.) within a catalog.

Method	Endpoint	Description
GET	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings`	List offerings in a catalog
POST	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings`	Create an offering
GET	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Get an offering
PUT	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Update an offering
DELETE	`/api/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Archive an offering

Example - Create an offering:

curl -X POST https://api.agentic.scope3.com/api/buyer/advertisers/12345/catalogs/cat_abc/offerings \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offeringId": "sku_001",
    "title": "Wireless Headphones",
    "description": "Premium noise-cancelling headphones",
    "price": 299.99,
    "currency": "USD",
    "landingUrl": "https://example.com/products/headphones"
  }'

MCP Tools

The Buyer MCP server uses a generic tool pattern rather than individual tools per resource. AI agents interact with the full REST API surface through four tools:

Tool	Description
`ask_about_capability`	Query the API documentation to look up correct endpoint paths, field names, and request schemas. Call this before `api_call` when unsure of the exact interface.
`api_call`	Authenticated HTTP proxy to any buyer REST endpoint. Supports all methods (GET, POST, PUT, DELETE) with full request/response passthrough.
`help`	List all available API endpoints with descriptions and categories.
`health`	Health check to verify the API is reachable.

Required workflow for AI agents: Always call ask_about_capability first to retrieve accurate field names and schemas before calling api_call. Field names are camelCase (e.g. advertiserId, not advertiser_id).

Using `api_call`

The api_call tool proxies to any endpoint under /api/buyer/. It handles authentication automatically. MCP Example - List Advertisers:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "GET",
      "path": "/api/buyer/advertisers",
      "query": { "includeAccounts": true }
    }
  }
}

MCP Example - Create Advertiser:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "POST",
      "path": "/api/buyer/advertisers",
      "body": {
        "name": "Acme Corp",
        "brand": { "domain": "acme.com" }
      }
    }
  }
}

MCP Example - Get Reporting:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "GET",
      "path": "/api/buyer/advertisers/adv_123/reporting",
      "query": { "days": 7 }
    }
  }
}

Supported Endpoint Families

The api_call tool allows access to:

Endpoint Family	Example Operations
`/api/buyer/advertisers/*`	Advertiser CRUD, brand, conversion events, test cohorts, measurement config, accounts, catalogs, offerings
`/api/buyer/campaigns/*`	Campaign CRUD, execute, pause
`/api/buyer/discovery/*`	Product discovery and selection
`/api/buyer/creative-sets/*`	Creative set and asset management
`/api/buyer/media-buys/*`	View media buy status and delivery
`/api/buyer/reporting/*`	Impressions, spend, clicks metrics
`/api/buyer/sales-agents/*`	Partner agent discovery and account registration
`/api/buyer/signals/*`	Audience signal listing

Response Format

All responses follow a consistent structure:

{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response:

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Advertiser not found"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Support

For technical support, contact us at support@scope3.com.

Buyer API

​Buyer API Reference

​Overview

​Connection Methods

​REST API (Recommended for traditional integrations)

​MCP (Model Context Protocol) for AI Agents

​OpenAPI Specification

​Authentication

Get API Key

​REST API Endpoints

​Advertisers

​Conversion Events

​Test Cohorts

​Measurement Config

​Brands

​Campaigns

​Creative Sets

​Media Buys

​Reporting

​Partner Accounts

​Partner Agents

​Catalogs

​Offerings

​MCP Tools

​Using api_call

​Supported Endpoint Families

​Response Format

​Support

Buyer API Reference

Overview

Connection Methods

REST API (Recommended for traditional integrations)

MCP (Model Context Protocol) for AI Agents

OpenAPI Specification

Authentication

REST API Endpoints

Advertisers

Conversion Events

Test Cohorts

Measurement Config

Brands

Campaigns

Creative Sets

Media Buys

Reporting

Partner Accounts

Partner Agents

Catalogs

Offerings

MCP Tools

Using `api_call`

Supported Endpoint Families

Response Format

Support