Migrating from v1 to v2

The v2 Interchange API is a fundamental simplification of v1. The surface is smaller, the conventions are agent-first, and the platform now extends across both the buy side and the sell side. v1 is frozen — every integration must migrate to v2. This guide walks you through what changed and how to translate the calls you already use today.

Overview

v2 is a redesign — not a refactor. The core ideas behind Scope3 (allocation over bidding, agentic orchestration, signal-driven media quality) are unchanged. What changed is the API contract.

Simpler surface

Single endpoint, single object, full intent (SESOFI). RESTful resources replace v1’s per-action verb endpoints.

Agent-first MCP

Two generic MCP wrappers — api_call and ask_about_capability — replace dozens of per-domain MCP tools.

AAO marketplace

Native support for the Agentic Advertising Organization (AAO) — discover and buy from storefronts.

Measurement engine

First-class endpoints for hypotheses, test plans, learning cycles, and measurement data ingestion.

v2 is required. v1 is frozen and will be retired — every integration must move to v2. This guide is the path.

You can migrate incrementally: v1 and v2 run side by side, so you can move one advertiser, campaign, or workflow at a time rather than cutting over in a single shot.

Key conceptual changes

Brand Agent → Advertiser

v1 used the term Brand Agent as the top-level container for campaigns, creatives, and brand stories. v2 calls this an Advertiser. The model is the same, the name is industry-standard.

v1 term	v2 term
Brand Agent	Advertiser
Brand Agent Standard	Advertiser Standard (rolled into measurement / discovery)
Tactic	Media Buy (already in v1, now consistent)
Outcome Agent	Measurement Engine + Hypotheses + Test Plans

MCP tool model: per-domain → generic

In v1, each domain had its own MCP tool — brand-agent-create, campaign-update, media-buy-execute, and so on. Agents had to memorize dozens of tool names and argument shapes. In v2, every operation goes through one of three generic tools:

Tool	Purpose
`health`	Probe API connectivity
`ask_about_capability`	Ask the API in natural language what it can do — returns operations, fields, and display requirements
`api_call`	Execute any REST endpoint via a named `operation`, with `pathParams`, `body`, and `params`

The agent discovers capabilities at runtime via ask_about_capability and then dispatches through api_call. There is nothing to register, nothing to update when the API gains new operations.

Skill files

Both buyer and storefront roles ship a skill file that fully describes the API for any agent that can read Markdown:

Role	Skill name	Skill URL
Buyer	`scope3-agentic-buyer` (v2.0.0)	`https://api.interchange.io/api/v2/buyer/skill.md`
Storefront	`scope3-agentic-storefront` (v2.0.0)	`https://api.interchange.io/api/v2/storefront/skill.md`

Point a custom agent at the skill file and it has end-to-end understanding of the API — operations, required fields, display rules, and workflow guidance.

New surfaces in v2

Surface	What it is
Storefronts	Sell-side companion API for inventory owners listing products to buyers
Measurement engine	Hypotheses, test plans, learning cycles, belief state, and feedback loops
AAO compliance	Native Agentic Advertising Organization (AAO) support — discover and authenticate against storefronts
Partner agents marketplace	Browse and connect to third-party signals, sales, and creative agents
Discovery	First-class product discovery with persistent `discoveryId` and proposal application
Property lists	Manage allow/block lists at advertiser scope
Frequency cap & pacing	Reusable configs at advertiser level, applied to campaigns and media buys
Audit logs / Tasks / Notifications	Operational visibility for long-running and async operations

Endpoint mapping

v1 used verb-style RPC paths (/brand-agent-create, /campaign-update). v2 is fully RESTful with resource-oriented paths under /api/v2/buyer and /api/v2/storefront.

v2 base URLs (canonical, pinned to v2 — these will keep serving v2 after future major versions):

Buyer REST: https://api.interchange.io/api/v2/buyer
Storefront REST: https://api.interchange.io/api/v2/storefront

The unversioned forms (/api/buyer, /api/storefront) 308-redirect to whatever major version is currently stable — see Versioning.ADCP property-list resolution lives at the app-level top — GET /lists/:listId.

Core resources

v1 endpoint	v2 endpoint	Notes
`POST /brand-agent-create`	`POST /advertisers`	Renamed; `brand` field now required
`POST /brand-agent-update`	`PUT /advertisers/{advertiserId}`	RESTful update
`POST /brand-agent-list`	`GET /advertisers`	Standard list
`POST /brand-agent-get`	`GET /advertisers/{advertiserId}`
`POST /brand-agent-delete`	`DELETE /advertisers/{advertiserId}`
`POST /campaign-create`	`POST /campaigns`	New shape: nested `flightDates`, `budget`, `performanceConfig`
`POST /campaign-update`	`PUT /campaigns/{campaignId}`
`POST /campaign-list`	`GET /campaigns`	Filter via query params
`POST /campaign-get`	`GET /campaigns/{campaignId}`
`POST /campaign-delete`	`DELETE /campaigns/{campaignId}`
`POST /campaign-validate-brief`	(folded into `discover-products`)	Brief validation now happens during discovery
`POST /media-buy-create`	(managed via campaigns)	Media buys are created by campaign execution / auto-select
`POST /media-buy-execute`	`POST /campaigns/{campaignId}/execute`	Execution is now campaign-scoped
`POST /media-buy-list`	`GET /campaigns/{campaignId}/media-buy-status`	Returns status for all media buys on a campaign
`POST /signals-list` (v1 partner API)	`GET /signals` (storefront) / via discovery	Signals surface differently per role
`POST /creative-create`	`POST /campaigns/{campaignId}/creatives/create`	Creatives are now campaign-nested
`POST /creative-update` / `delete` / `get`	`PUT/DELETE/GET /campaigns/{campaignId}/creatives/{creativeId}`	RESTful, manifest-based
`POST /creative-assign`	`GET /campaigns/{campaignId}/creativeManifest`	Manifest-driven assignment replaces per-call assign
`POST /tactic-*`	(replaced)	Tactics are subsumed by media buys + allocations
`POST /outcomes-agent-*`	`/advertisers/{advertiserId}/hypotheses` etc.	Outcome agents become the measurement engine
`POST /service-token-*`	(admin UI / unchanged auth model)	Use SSO or API keys; service tokens still work

v2-only endpoints (no v1 equivalent)

These exist only on v2 and are central to the new platform:

POST /discovery/discover-products and /discovery/{discoveryId}/... — persistent product discovery
POST /campaigns/{campaignId}/auto-select-products — AI-driven product selection and budget allocation
GET /audit-logs — full audit trail
GET /tasks/{taskId} — track async operations
GET /notifications (and unread counts via help / ask_about_capability)
GET /storefronts / POST /storefronts (storefront role) — sell-side surfaces
/advertisers/{advertiserId}/measurement-config, hypotheses, test-plans, learning-cycle/run, belief-state, testability — measurement engine
/advertisers/{advertiserId}/property-lists/... — allow/block lists
/advertisers/{advertiserId}/event-sources and /measurement-data/sync — conversion ingestion
/advertisers/{advertiserId}/catalogs and /syndicate — partner-agent catalog distribution
/accounts/current, /accounts, /accounts/create-child — multi-tenant account hierarchy
/notification-preferences and frequency-cap / pacing-period configs

Side-by-side: creating a campaign

v1 — brand-agent + campaign
v2 — advertiser + campaign

# Step 1: create the brand agent
curl -X POST "https://api.interchange.io/v1/brand-agent-create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp"
  }'

# Step 2: create the campaign
curl -X POST "https://api.interchange.io/v1/campaign-create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandAgentId": "agent_123",
    "name": "Q1 Launch",
    "startDate": "2026-02-05",
    "endDate":   "2026-02-28",
    "budget":    50000
  }'

# Step 1: create the advertiser
curl -X POST "https://api.interchange.io/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "Acme Corp",
    "brand": "acme.com"
  }'

# Step 2: create the campaign
curl -X POST "https://api.interchange.io/api/v2/buyer/campaigns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": 24,
    "name":         "Q1 Launch",
    "flightDates":  {
      "startDate": "2026-02-05T00:00:00Z",
      "endDate":   "2026-02-28T23:59:59Z"
    },
    "budget": {
      "total":    50000,
      "currency": "USD"
    },
    "performanceConfig": {
      "optimizationGoals": [
        { "kind": "metric", "metric": "completed_views" }
      ]
    }
  }'

Notable differences:

brandAgentId (string) → advertiserId (number)
startDate / endDate flat fields → nested flightDates object with ISO 8601 datetimes
budget: 50000 → nested budget object with explicit currency
New optional performanceConfig.optimizationGoals[] for goal-based optimization
Required brand field on advertiser create (e.g., "acme.com")

Authentication changes

The bearer-token model from v1 still works in v2. What’s new:

OAuth for AI agents

Connect Claude, ChatGPT, and other MCP-aware agents via OAuth. No API keys to manage.

SSO

SAML / OIDC SSO for enterprise org sign-in.

AAO OAuth

API keys

Same Bearer scope3_... format as v1 — your existing keys keep working.

If you only use API keys today, no auth changes are required. Just point your existing key at the v2 base URL.

Breaking changes checklist

When you migrate, audit for these:

Skill / MCP migration

If your v1 integration drove the API through per-domain MCP tools, you’ll dispatch through the generic v2 tools instead.

v1 — per-domain tool
v2 — generic api_call

// MCP tool call: brand-agent-create
{
  "name": "brand-agent-create",
  "arguments": {
    "name": "Acme Corp"
  }
}

// MCP tool call: api_call with named operation
{
  "name": "api_call",
  "arguments": {
    "operation": "create_advertiser",
    "body": {
      "name":  "Acme Corp",
      "brand": "acme.com"
    }
  }
}

The recommended pattern for any v2 agent:

Discover the operation

Call ask_about_capability with a natural-language description of what you want to do. The response lists candidate operations, required fields, display requirements, and workflow notes.

Verify every field has a source

Walk every field in body, pathParams, and params and name where it came from — a previous response, the user, or ask_about_capability. Never invent IDs or fabricate values.

Dispatch via api_call

Pass operation, pathParams, body, and params to api_call. The named operation enum prevents hallucinated endpoints and wrong HTTP methods.

Present results per the display rules

Each operation’s ask_about_capability response describes what to show the user (status, IDs, account links, sandbox flag, etc.). Show those fields — never collapse to vague prose.

Use the buyer MCP endpoint and canonical storefront agent URL below:

Role	URL
Buyer	`https://api.interchange.io/mcp/buyer`
Storefront	`https://interchange.io`

Sandbox

v2 has first-class sandbox support. Set "sandbox": true when creating an advertiser and every ADCP operation under that advertiser routes to sandbox accounts — no real spend, no production side effects.

Sandbox guide

Learn how to test campaigns, discovery, and media-buy flows safely.

The sandbox flag is immutable after the advertiser is created. Decide up front whether the advertiser is for production or testing.

Getting help

Quick Start

Connect an agent and make your first call in minutes.

API Reference

Browse every v2 endpoint with request and response schemas.

Authentication

OAuth, SSO, and API key setup.

Built for Agents

Detailed setup for Claude, ChatGPT, Cursor, and custom agents.

Skill File

Why a skill file beats hand-written tool wrappers.

Support

Email support@scope3.com for migration help.

Welcome

Core Concepts

Connect

Cross-Cutting Reference

Release Notes

Migrating from v1 to v2

Migrating from v1 to v2

Overview

Simpler surface

Agent-first MCP

AAO marketplace

Measurement engine

Key conceptual changes

Brand Agent → Advertiser

MCP tool model: per-domain → generic

Skill files

New surfaces in v2

Endpoint mapping

Core resources

v2-only endpoints (no v1 equivalent)

Side-by-side: creating a campaign

Authentication changes

OAuth for AI agents

SSO

AAO OAuth

API keys

Breaking changes checklist

Skill / MCP migration

Sandbox

Sandbox guide

Getting help

Quick Start

API Reference

Authentication

Built for Agents

Skill File

Support

​Migrating from v1 to v2

​Overview

Simpler surface

Agent-first MCP

AAO marketplace

Measurement engine

​Key conceptual changes

​Brand Agent → Advertiser

​MCP tool model: per-domain → generic

​Skill files

​New surfaces in v2

​Endpoint mapping

​Core resources

​v2-only endpoints (no v1 equivalent)

​Side-by-side: creating a campaign

​Authentication changes

OAuth for AI agents

SSO

AAO OAuth

API keys

​Breaking changes checklist

​Skill / MCP migration

​Sandbox

Sandbox guide

​Getting help

Quick Start

API Reference

Authentication

Built for Agents

Skill File

Support

Migrating from v1 to v2

Overview

Key conceptual changes

Brand Agent → Advertiser

MCP tool model: per-domain → generic

Skill files

New surfaces in v2

Endpoint mapping

Core resources

v2-only endpoints (no v1 equivalent)

Side-by-side: creating a campaign

Authentication changes

Breaking changes checklist

Skill / MCP migration

Sandbox

Getting help