Skip to main content
POST
/
inventory-sources
Create inventory source
curl --request POST \
  --url https://api.interchange.io/api/v2/storefront/inventory-sources \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Retail Network Agent"
}
'
{
  "id": "<string>",
  "sourceId": "<string>",
  "name": "<string>",
  "executionType": "<string>",
  "agentId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "endpointUrl": "<string>",
  "description": "<string>",
  "authConfigured": true,
  "oauth": {
    "authorizationUrl": "<string>",
    "agentId": "<string>",
    "agentName": "<string>"
  },
  "managedSa": {
    "connectionId": "<string>",
    "tenantId": "<string>",
    "adServer": {
      "type": "google_ad_manager",
      "networkCode": "12345678"
    },
    "lastError": "<string>",
    "lastTestedAt": "2023-11-07T05:31:56Z",
    "provisionedAt": "2023-11-07T05:31:56Z",
    "deactivatedAt": "2023-11-07T05:31:56Z"
  },
  "linkedStorefront": {
    "buyer": {
      "storefrontId": "1234",
      "platformId": "acme-media",
      "name": "Acme Media",
      "publisherDomain": "acme.com",
      "operatorDomain": "scope3.com",
      "brandName": "Scope3",
      "logoUrl": "<string>",
      "regions": [
        "<string>"
      ],
      "description": "<string>",
      "channels": [
        "<string>"
      ],
      "website": "<string>",
      "demandContactName": "<string>",
      "demandContactEmail": "<string>",
      "operatorDomainVerified": true,
      "adapterCredentialMode": "BYOK",
      "plan": "basic",
      "transacting": true,
      "archivedAt": "2023-11-07T05:31:56Z",
      "capabilities": {
        "offersCreativeReview": false,
        "offersCampaignApproval": false,
        "offersProductComposition": false
      },
      "compositionPricing": {
        "targetPercentile": "p75",
        "rateCard": {
          "facts": []
        }
      },
      "capabilitiesLocked": true,
      "advertiseAsAgent": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "businessProfile": {
        "summary": "<string>",
        "agentName": "<string>",
        "agentPersonality": "<string>",
        "propertyCount": 5000,
        "channels": [],
        "regions": [
          "UK",
          "EMEA"
        ],
        "verticals": [
          "sports",
          "entertainment"
        ],
        "publisherDomains": [
          "pitchside.co.uk",
          "football.pitchside.co.uk"
        ],
        "evidenceUrls": [
          "<string>"
        ],
        "notes": "<string>",
        "updatedBy": "<string>"
      }
    },
    "seller": {
      "storefrontId": "1234",
      "platformId": "acme-media",
      "name": "Acme Media",
      "publisherDomain": "acme.com",
      "operatorDomain": "scope3.com",
      "brandName": "Scope3",
      "logoUrl": "<string>",
      "regions": [
        "<string>"
      ],
      "description": "<string>",
      "channels": [
        "<string>"
      ],
      "website": "<string>",
      "demandContactName": "<string>",
      "demandContactEmail": "<string>",
      "operatorDomainVerified": true,
      "adapterCredentialMode": "BYOK",
      "plan": "basic",
      "transacting": true,
      "archivedAt": "2023-11-07T05:31:56Z",
      "capabilities": {
        "offersCreativeReview": false,
        "offersCampaignApproval": false,
        "offersProductComposition": false
      },
      "compositionPricing": {
        "targetPercentile": "p75",
        "rateCard": {
          "facts": []
        }
      },
      "capabilitiesLocked": true,
      "advertiseAsAgent": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "businessProfile": {
        "summary": "<string>",
        "agentName": "<string>",
        "agentPersonality": "<string>",
        "propertyCount": 5000,
        "channels": [],
        "regions": [
          "UK",
          "EMEA"
        ],
        "verticals": [
          "sports",
          "entertainment"
        ],
        "publisherDomains": [
          "pitchside.co.uk",
          "football.pitchside.co.uk"
        ],
        "evidenceUrls": [
          "<string>"
        ],
        "notes": "<string>",
        "updatedBy": "<string>"
      }
    },
    "requestMessage": "<string>",
    "responseMessage": "<string>",
    "requestedAt": "2023-11-07T05:31:56Z",
    "respondedAt": "2023-11-07T05:31:56Z",
    "cancelledAt": "2023-11-07T05:31:56Z"
  },
  "isAdapterSource": true
}

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json
​
name
string
required

Display name for the inventory source

Required string length: 1 - 255
Example:

"Retail Network Agent"

​
sourceId
string

Unique identifier for this source within the storefront. Defaults to a slugified version of the name if not provided.

Required string length: 1 - 255
Example:

"retail-network-agent"

​
executionType
enum<string>
default:AGENT

Only external AGENT inventory sources can be created through this endpoint. MANAGED_SALES_AGENT, LINKED_STOREFRONT, and MODULAR_SOURCE rows are created by their dedicated provisioning/linking flows. Storefront-level ADAPTER dispatch is configured on the storefront, not as an inventory source.

Available options:
AGENT
​
type
enum<string>

Agent type — required when executionType is "AGENT"

Available options:
SALES,
SIGNAL,
CREATIVE,
OUTCOME
​
endpointUrl
string<uri>

Agent endpoint URL — required when executionType is "AGENT"

Maximum string length: 2048
​
protocol
enum<string>

Agent protocol — required when executionType is "AGENT"

Available options:
MCP,
A2A
​
authenticationType
enum<string>

Auth method for the agent — required when executionType is "AGENT"

Available options:
API_KEY,
NO_AUTH,
JWT,
OAUTH
​
auth
object

Initial credentials for testing. Required for non-OAUTH agents when executionType is "AGENT".

​
description
string

Agent description

Maximum string length: 2000

Response

Create inventory source

Inventory source response

​
id
string
required

Globally unique surrogate id (BIGINT serialized as string). Use this when acting on rows the caller does not own (e.g. a seller approving an inbound link).

​
sourceId
string
required

Storefront-scoped identifier — unique within the row owner's storefront. Use this for actions on the caller's own rows; use id for cross-customer actions.

​
name
string
required

Display name

​
executionType
string
required

Execution type

​
status
enum<string>
required

Source lifecycle status

Available options:
PENDING,
ACTIVE,
DISABLED
​
agentId
string | null
required

Linked agent ID (when executionType is agent)

​
createdAt
string<date-time>
required

Creation timestamp (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
updatedAt
string<date-time>
required

Last update timestamp (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
type
enum<string> | null

Agent type

Available options:
SALES,
SIGNAL,
CREATIVE,
OUTCOME
​
endpointUrl
string | null

Agent endpoint URL

​
protocol
enum<string> | null

Agent protocol

Available options:
MCP,
A2A
​
description
string | null

Agent description

​
authenticationType
enum<string> | null

Agent authentication type

Available options:
API_KEY,
NO_AUTH,
JWT,
OAUTH
​
authConfigured
boolean

Whether the agent has authentication configured

​
oauth
object

OAuth authorization info (for OAUTH agents)

​
managedSa
object

Embedded-sales-agent state when executionType is MANAGED_SALES_AGENT. Null/absent for external AGENT-type sources. The current REST surface (/api/v2/storefront/esa/...) remains the way to mutate this state today; subsequent PRs will move those actions under /api/v2/storefront/inventory-sources/:sourceId/....

​
linkedStorefront
object

Link state when executionType is LINKED_STOREFRONT. Stored inline on this row (the buyer owns it; the seller has permission to update the link_* fields when approving / rejecting / cancelling). Null/absent for other kinds. Mutate via /api/v2/storefront/links/....

​
reportingType
enum<string> | null

How the underlying agent reports delivery (WEBHOOK, BUCKET, POLLING). Mirrors the AdCP-spec values used when registering the agent. Projected from the joined adcp_agent row; null for non-AGENT sources.

Available options:
WEBHOOK,
BUCKET,
POLLING
​
reportingPollingCadence
enum<string> | null

Polling cadence (DAILY, MONTHLY) — only meaningful when reportingType is POLLING. Projected from the joined adcp_agent row; null for non-AGENT sources or non-polling reporting.

Available options:
DAILY,
MONTHLY
​
isAdapterSource
boolean

True when this source is routed through an official Scope3-hosted adapter (storefront routing_mode is ADAPTER and the source_id matches the configured adapter). When true, the UI labels this as an official adapter rather than a generic external sales agent.