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>"
      },
      "sellsThirdPartyInventory": true,
      "defaultCurrency": "<string>",
      "paymentCurrencies": [
        "<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>"
      },
      "sellsThirdPartyInventory": true,
      "defaultCurrency": "<string>",
      "paymentCurrencies": [
        "<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 and MODULAR_SOURCE rows are created by their dedicated provisioning flows; LINKED_STOREFRONT sources are never created or persisted — storefront interchange is resolved at runtime from the ambient wholesale pool. 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,
BASIC_AUTH
​
auth
object

Optional for most schemes. NO_AUTH sources need no credentials at all, and OAUTH sources are authorized through their own flow — neither carries an auth payload. BASIC_AUTH and API_KEY sources may include credentials here, or be created without them and start PENDING, with the secret collected later through the secure credential form rather than at create time (for BASIC_AUTH use { type: "basic", username, password }). JWT is the exception: its secret must be supplied here at create time, because the secure credential form cannot collect JWT yet.

​
oauthAudience
string<uri>

OAuth audience / resource indicator for OAUTH agents (the protected-resource URI the agent gateway validates, e.g. "https://platform.example.com"). When set, the OAuth flow requests a token whose aud claim targets this resource (sent as both Auth0 audience and RFC 8707 resource). Leave unset to auto-discover it from the agent's RFC 9728 protected-resource metadata.

Maximum string length: 2048
Example:

"https://platform.example.com"

​
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,
BASIC_AUTH
​
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

Always null. Storefront interchange runs through the ambient wholesale pool: a curator discovers any LISTED storefront’s wholesale inventory automatically, with no per-counterparty link to establish. Retained for response-shape stability.

​
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.