​

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)

• 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

# Step 1: create the brand agent
curl -X POST "https://api.agentic.scope3.com/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.agentic.scope3.com/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.agentic.scope3.com/api/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.agentic.scope3.com/api/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" }
      ]
    }
  }'

• 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

​

Breaking changes checklist

• Path style — every v1 verb endpoint (e.g. /campaign-create) maps to a RESTful resource (e.g. POST /campaigns)
• brandAgentId → advertiserId — and the type changed from string to number
• Date fields — flat startDate / endDate are now nested under flightDates with required ISO 8601 datetimes (with Z suffix)
• Budget — scalar budget: 50000 is now an object with total and currency
• Required brand — advertiser create now requires a brand domain (e.g. "acme.com")
• Creatives — now nested under /campaigns/{campaignId}/creatives and use a manifest model rather than per-call assign
• Tactics — removed as a top-level concept; functionality lives in media buys + allocations
• Outcome agents — replaced by the measurement engine (hypotheses, test plans, learning cycles)
• MCP tools — per-domain v1 tools are not available in v2; use api_call + ask_about_capability
• Field naming — v2 is strict camelCase. advertiser_id is rejected; use advertiserId. flight_dates is rejected; use flightDates.
• Optimization goals — now live on performanceConfig.optimizationGoals[] with kind: "event" | "metric". Valid metric values: clicks, views, completed_views, viewed_seconds, attention_seconds, attention_score, engagements, follows, saves, profile_visits.
• Creative assignment — done via creativeManifest rather than per-creative creative-assign calls

​

Skill / MCP migration

// 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"
    }
  }
}

​

Sandbox

​

Getting help