Skip to main content
You’re viewing the v2 beta documentation. The API is in active development - breaking changes may occur before final release. For production use, switch to v1 using the version selector above.

​
Storefront API Reference

​
Overview

The Scope3 Storefront API v2 provides capabilities for publishers and technology partners to set up and manage storefronts, configure inventory sources, register agents, and handle billing through both REST and MCP (Model Context Protocol) interfaces.

​
Connection Methods

Standard HTTP methods with JSON request/response bodies.Production:
https://api.agentic.scope3.com/api/v2/storefront
Staging:
https://api.agentic.staging.scope3.com/api/v2/storefront
Example:
curl https://api.agentic.scope3.com/api/v2/storefront \
  -H "Authorization: Bearer scope3_your_api_key_here"

​
OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

​
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

​
Storefront Capabilities

The Storefront API provides access to:
  • Storefronts — Create, view, update, and delete storefronts
  • Inventory Sources — Manage inventory sources and register agents within storefronts
  • Billing — Stripe Connect provisioning, account status, transactions, and payouts

​
REST API Endpoints

​
Storefronts

Manage storefronts for your publisher integration. Each customer may have at most one storefront.
MethodEndpointDescription
POST/api/v2/storefrontCreate a storefront
GET/api/v2/storefrontGet your storefront
PUT/api/v2/storefrontUpdate storefront
DELETE/api/v2/storefrontDelete storefront and all its inventory sources
GET/api/v2/storefront/readinessCheck if storefront is ready to go live
Example — Create Storefront: 
curl -X POST https://api.agentic.scope3.com/api/v2/storefront \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CVS Media Network",
    "publisherDomain": "cvs.com",
    "platformId": "cvs-media"
  }'
Example — Check Readiness: 
curl https://api.agentic.scope3.com/api/v2/storefront/readiness \
  -H "Authorization: Bearer scope3_your_api_key_here"

​
Inventory Sources

Manage inventory sources within a storefront. To register an agent, create an inventory source with executionType: "agent" and provide the agent’s endpoint URL and protocol.
MethodEndpointDescription
GET/api/v2/storefront/inventory-sourcesList inventory sources
POST/api/v2/storefront/inventory-sourcesCreate inventory source
GET/api/v2/storefront/inventory-sources/:sourceIdGet inventory source
PUT/api/v2/storefront/inventory-sources/:sourceIdUpdate inventory source
DELETE/api/v2/storefront/inventory-sources/:sourceIdDelete inventory source
Example — Register an Agent as an Inventory Source: 
curl -X POST https://api.agentic.scope3.com/api/v2/storefront/inventory-sources \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "snap-ads-agent",
    "name": "Snap Ads Agent",
    "executionType": "agent",
    "type": "SALES",
    "endpointUrl": "https://my-agent.example.com/mcp",
    "protocol": "MCP",
    "authenticationType": "API_KEY"
  }'

​
Storefront Billing

Stripe Connect billing integration for storefronts.
MethodEndpointDescription
POST/api/v2/storefront/billing/connectProvision Stripe Connect account
GET/api/v2/storefront/billingGet billing configuration
GET/api/v2/storefront/billing/statusGet Stripe account verification status and balance
GET/api/v2/storefront/billing/transactionsList balance transactions (cursor-paginated)
GET/api/v2/storefront/billing/payoutsList payouts (cursor-paginated)
GET/api/v2/storefront/billing/onboardGet a fresh Stripe onboarding URL
Query Parameters for transactions and payouts:
  • limit — Maximum results per page (1–100, default 25)
  • starting_after — Cursor for pagination (ID of last item from previous page)
Example — Provision Stripe Connect: 
curl -X POST https://api.agentic.scope3.com/api/v2/storefront/billing/connect \
  -H "Authorization: Bearer scope3_your_api_key_here"
Example — List Transactions: 
curl "https://api.agentic.scope3.com/api/v2/storefront/billing/transactions?limit=25" \
  -H "Authorization: Bearer scope3_your_api_key_here"

​
MCP Tools

The v2 Storefront MCP server uses a generic tool pattern. AI agents interact with the full REST API surface through these tools:
ToolDescription
ask_about_capabilityQuery 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_callAuthenticated HTTP proxy to any v2 storefront REST endpoint. Supports all methods (GET, POST, PUT, PATCH, DELETE) with full request/response passthrough.
healthHealth 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. agentId, not agent_id).

​
Supported Endpoint Families

The api_call tool allows access to:
Endpoint FamilyExample Operations
/api/v2/storefrontStorefront CRUD, readiness checks
/api/v2/storefront/inventory-sources/*Inventory source and agent management
/api/v2/storefront/billing/*Stripe Connect provisioning, transactions, payouts

​
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": "Agent not found"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Support

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