Philosophy

The v2 API is designed for a world where AI agents are first-class operators of advertising — not where humans drive a console while agents fetch them data. Every shape, every endpoint, and every default reflects that.

​

Agent-first, not agent-friendly

A lot of APIs say “we support agents” and mean “we have a Python SDK.” v2 treats AI agents as the primary caller. That changes a few things:

​

One endpoint per object, full intent in the body (SESOFI)

The architectural pattern that keeps the surface coherent:

Each high-level intent (update an advertiser, run a media buy, refine a discovery query) maps to one endpoint that accepts one object describing the full intent.

This is the opposite of the “atomic CRUD on every sub-resource” instinct. SESOFI cuts agent round-trips, eliminates partial-state bugs, and makes the intent legible in transcript form. REST endpoints still exist at the granular level — they’re useful for UIs and programmatic clients — but MCP tools are composite by design. An agent calling update_advertiser does not need to know that measurement config and conversion events live in different tables.

​

ADCP-aligned by default

v2 uses the Ad Context Protocol as its inter-agent contract. That means:

• Sales agents implement ADCP get_products and create_media_buy.
• Signal and outcome agents implement ADCP capability discovery.
• Reporting payloads follow the ADCP get_media_buy_delivery schema.
• Notification webhooks include ADCP-spec metadata (notification_type, sequence_number, next_expected_at).

When ADCP and Scope3 conventions disagree, ADCP wins. We extend ADCP through namespaced extensions (scope3, sandbox) rather than forking it.

​

Buyer and storefront are separate skills

v1 lumped buyer-side and storefront-side capabilities together, which made it hard to give agents focused tool surfaces. v2 splits them cleanly: Both skills speak the same auth model and share the v2 schema layer, but they expose disjoint endpoints under /api/buyer/* and /api/storefront/*. Agents pick the skill that matches their job description; they never have to filter through tools they cannot use.

​

AAO marketplace as the registry of trust

Scope3 does not unilaterally decide which agents are real. The Agentic Advertising Organization maintains a public registry and a compliance pipeline — and v2 enforces it:

• Marketplace agents must appear in the AAO registry to be activated.
• Their compliance status (passing, pending, not-passing) is read live.
• Self-registered agents (your own endpoints) bypass the marketplace check but go through the same activation probe.

This keeps the marketplace open and verifiable. The registry is the source of truth, not a Scope3 allowlist.

​

Human-in-the-loop, by design

Agents operate fast. Some decisions still belong to a human:

• Optimization suggestions are generated by agents, surfaced as notifications (optimization.suggestion_received), and require explicit acknowledgement before they apply.
• Creative approval flows route through creative.approved / creative.rejected events with reviewer attribution.
• Custom contracts are generated for review and signed via SharePoint or GCS-hosted documents — the API never auto-signs.

The system optimizes for “agent moves work forward, human approves the irreversible step” — not for full autopilot.

​

Sandbox-first development

Every reasoning step in v2 — capability discovery, OAuth, reporting — has a sandbox path. ADCP agents that declare sandbox: true in their capabilities get exercised through their sandbox endpoints during integration. Demo reporting data is one query parameter away (?demo=true). New skills land on sandbox first and graduate to production explicitly. This makes integration safe to iterate on. You don’t need a live publisher deal to test a sales agent end-to-end.

​

What this means for callers

​

Next steps