> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Philosophy

> How v2 thinks about agents, intent, marketplaces, and the buyer/storefront split.

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:

<CardGroup cols={2}>
  <Card title="One endpoint, full intent" icon="bullseye">
    A campaign update is one call that carries every related decision —
    measurement config, conversion events, test cohorts — instead of five
    sequential calls the agent has to plan.
  </Card>

  <Card title="Stable resource taxonomies" icon="sitemap">
    Notification types, agent types, and resource names follow
    `resource.action` patterns so agents can build workflows around stable
    strings instead of free-form heuristics.
  </Card>

  <Card title="Explicit error semantics" icon="triangle-exclamation">
    Errors have machine-readable codes (`VALIDATION_ERROR`, `ACCESS_DENIED`,
    `NOT_FOUND`, …) plus a human-readable message. Agents can branch on the
    code; humans read the message.
  </Card>

  <Card title="Discoverable capabilities" icon="binoculars">
    Partner agents publish AdCP capabilities. Scope3 fetches them, caches them,
    and exposes them so callers can decide what's possible without trial and
    error.
  </Card>
</CardGroup>

## 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](https://adcontextprotocol.org) 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`).

AdCP defines how participants discover, negotiate, and execute. The
Interchange runs AdCP at scale and adds the operational layers the protocol
intentionally leaves out: contracts, billing, multi-agent aggregation,
governance, identity, observability.

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:

| Skill          | Audience                          | Scope                                                                 |
| -------------- | --------------------------------- | --------------------------------------------------------------------- |
| **Buyer**      | Brands, agencies, brand agents    | Advertisers, campaigns, media buys, creatives, reporting, storefronts |
| **Storefront** | Publishers, supply-side operators | Inventory products, AAO marketplace registration, sales agent OAuth   |

Both skills speak the same auth model and share the v2 schema layer, but they
expose disjoint endpoints under `/api/v2/buyer/*` and `/api/v2/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](https://agenticadvertising.org) maintains a
public registry and a compliance pipeline, and v2 consumes those signals:

* External inventory-source agents must appear in the AAO registry before they
  can be connected.
* Their compliance status (`passing`, `pending`, `not-passing`) is read live.
* A non-passing compliance verdict is surfaced as an advisory warning; it does
  not block storefront activation.
* Publisher authorization remains a separate `adagents.json` question surfaced
  as an advisory setup/product signal today.

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

<Steps>
  <Step title="Pick a skill">
    Decide whether you're acting as a buyer or a storefront. Mount only that
    skill's tools in your agent.
  </Step>

  <Step title="Author intents, not steps">
    When updating an entity, send the full new shape. Don't decompose the
    change into N sub-resource calls — the platform will do that for you.
  </Step>

  <Step title="Trust capabilities">
    Read the agent's discovered capabilities before deciding what's possible.
    Don't hardcode assumptions about what a sales agent supports — the
    capabilities tell you.
  </Step>

  <Step title="Listen for events">
    Subscribe to the notifications that match your workflow
    (`creative.approved`, `optimization.suggestion_received`, …) and let the
    platform tell you when to act.
  </Step>
</Steps>

<Tip>
  The shortest summary of v2: **stable taxonomies, composite intents,
  discoverable capabilities, separable skills, and a public registry of trust.**
  Everything else falls out of those five choices.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/v2/introduction">
    Start here for a tour of the v2 surface, auth, and the buyer/storefront
    split.
  </Card>

  <Card title="Built for Agents" icon="robot" href="/v2/setup/built-for-agents">
    A deeper look at how v2 shapes its tools and intents around AI agents as
    primary callers.
  </Card>

  <Card title="Migration Guide" icon="arrow-right-arrow-left" href="/v2/setup/migration-guide">
    Map every v1 tool, route, and concept onto its v2 equivalent.
  </Card>

  <Card title="Storefronts" icon="store" href="/v2/object-guides/storefront">
    Browse storefronts, register credentials per inventory source, and connect
    your buyer accounts to AdCP-compatible agents.
  </Card>
</CardGroup>