List inventory sources

curl --request GET \
  --url https://api.interchange.io/api/v2/storefront/inventory-sources \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.interchange.io/api/v2/storefront/inventory-sources"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/storefront/inventory-sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": "<string>",
    "sourceId": "<string>",
    "name": "<string>",
    "agentId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "connectionType": "AD_SERVER",
    "adServerProvider": "citrusad",
    "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>",
      "lastErrorCode": "<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>"
        ],
        "acceptedCountries": [
          "<string>"
        ],
        "acceptsAllCountries": true,
        "advertisingPolicyDisclosure": [],
        "advertisedCountries": [
          "<string>"
        ],
        "advertisedChannels": [
          "<string>"
        ],
        "description": "<string>",
        "channels": [
          "<string>"
        ],
        "website": "<string>",
        "discoveryCard": {
          "storefrontId": "<string>",
          "platformId": "<string>",
          "displayName": "<string>",
          "logoUrl": "<string>",
          "description": "<string>",
          "website": "<string>",
          "brandColors": {},
          "channels": [
            "<string>"
          ],
          "countries": [
            "<string>"
          ],
          "acceptsAllCountries": true,
          "coverageDeclarations": [
            {
              "channels": [
                "<string>"
              ],
              "countries": [
                "<string>"
              ],
              "acceptsAllCountries": true
            }
          ],
          "advertisingPolicies": "<string>",
          "coverage": {},
          "provenance": {
            "identity": {},
            "coverage": {}
          }
        },
        "demandContactName": "<string>",
        "demandContactEmail": "<string>",
        "operatorDomainVerified": true,
        "adapterCredentialMode": "BYOK",
        "plan": "basic",
        "transacting": true,
        "isPaused": true,
        "archivedAt": "2023-11-07T05:31:56Z",
        "capabilities": {
          "offersCreativeReview": false,
          "offersCampaignApproval": false,
          "offersProductComposition": false
        },
        "configuredCapabilities": {
          "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>"
        ],
        "acceptedCountries": [
          "<string>"
        ],
        "acceptsAllCountries": true,
        "advertisingPolicyDisclosure": [],
        "advertisedCountries": [
          "<string>"
        ],
        "advertisedChannels": [
          "<string>"
        ],
        "description": "<string>",
        "channels": [
          "<string>"
        ],
        "website": "<string>",
        "discoveryCard": {
          "storefrontId": "<string>",
          "platformId": "<string>",
          "displayName": "<string>",
          "logoUrl": "<string>",
          "description": "<string>",
          "website": "<string>",
          "brandColors": {},
          "channels": [
            "<string>"
          ],
          "countries": [
            "<string>"
          ],
          "acceptsAllCountries": true,
          "coverageDeclarations": [
            {
              "channels": [
                "<string>"
              ],
              "countries": [
                "<string>"
              ],
              "acceptsAllCountries": true
            }
          ],
          "advertisingPolicies": "<string>",
          "coverage": {},
          "provenance": {
            "identity": {},
            "coverage": {}
          }
        },
        "demandContactName": "<string>",
        "demandContactEmail": "<string>",
        "operatorDomainVerified": true,
        "adapterCredentialMode": "BYOK",
        "plan": "basic",
        "transacting": true,
        "isPaused": true,
        "archivedAt": "2023-11-07T05:31:56Z",
        "capabilities": {
          "offersCreativeReview": false,
          "offersCampaignApproval": false,
          "offersProductComposition": false
        },
        "configuredCapabilities": {
          "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,
    "agentCapabilityUid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "productModeReasons": [],
    "productPaths": [
      {
        "ready": true,
        "reasons": []
      }
    ]
  }
]

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

GET

inventory-sources

List inventory sources

curl --request GET \
  --url https://api.interchange.io/api/v2/storefront/inventory-sources \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.interchange.io/api/v2/storefront/inventory-sources"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/storefront/inventory-sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": "<string>",
    "sourceId": "<string>",
    "name": "<string>",
    "agentId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "connectionType": "AD_SERVER",
    "adServerProvider": "citrusad",
    "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>",
      "lastErrorCode": "<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>"
        ],
        "acceptedCountries": [
          "<string>"
        ],
        "acceptsAllCountries": true,
        "advertisingPolicyDisclosure": [],
        "advertisedCountries": [
          "<string>"
        ],
        "advertisedChannels": [
          "<string>"
        ],
        "description": "<string>",
        "channels": [
          "<string>"
        ],
        "website": "<string>",
        "discoveryCard": {
          "storefrontId": "<string>",
          "platformId": "<string>",
          "displayName": "<string>",
          "logoUrl": "<string>",
          "description": "<string>",
          "website": "<string>",
          "brandColors": {},
          "channels": [
            "<string>"
          ],
          "countries": [
            "<string>"
          ],
          "acceptsAllCountries": true,
          "coverageDeclarations": [
            {
              "channels": [
                "<string>"
              ],
              "countries": [
                "<string>"
              ],
              "acceptsAllCountries": true
            }
          ],
          "advertisingPolicies": "<string>",
          "coverage": {},
          "provenance": {
            "identity": {},
            "coverage": {}
          }
        },
        "demandContactName": "<string>",
        "demandContactEmail": "<string>",
        "operatorDomainVerified": true,
        "adapterCredentialMode": "BYOK",
        "plan": "basic",
        "transacting": true,
        "isPaused": true,
        "archivedAt": "2023-11-07T05:31:56Z",
        "capabilities": {
          "offersCreativeReview": false,
          "offersCampaignApproval": false,
          "offersProductComposition": false
        },
        "configuredCapabilities": {
          "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>"
        ],
        "acceptedCountries": [
          "<string>"
        ],
        "acceptsAllCountries": true,
        "advertisingPolicyDisclosure": [],
        "advertisedCountries": [
          "<string>"
        ],
        "advertisedChannels": [
          "<string>"
        ],
        "description": "<string>",
        "channels": [
          "<string>"
        ],
        "website": "<string>",
        "discoveryCard": {
          "storefrontId": "<string>",
          "platformId": "<string>",
          "displayName": "<string>",
          "logoUrl": "<string>",
          "description": "<string>",
          "website": "<string>",
          "brandColors": {},
          "channels": [
            "<string>"
          ],
          "countries": [
            "<string>"
          ],
          "acceptsAllCountries": true,
          "coverageDeclarations": [
            {
              "channels": [
                "<string>"
              ],
              "countries": [
                "<string>"
              ],
              "acceptsAllCountries": true
            }
          ],
          "advertisingPolicies": "<string>",
          "coverage": {},
          "provenance": {
            "identity": {},
            "coverage": {}
          }
        },
        "demandContactName": "<string>",
        "demandContactEmail": "<string>",
        "operatorDomainVerified": true,
        "adapterCredentialMode": "BYOK",
        "plan": "basic",
        "transacting": true,
        "isPaused": true,
        "archivedAt": "2023-11-07T05:31:56Z",
        "capabilities": {
          "offersCreativeReview": false,
          "offersCampaignApproval": false,
          "offersProductComposition": false
        },
        "configuredCapabilities": {
          "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,
    "agentCapabilityUid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "productModeReasons": [],
    "productPaths": [
      {
        "ready": true,
        "reasons": []
      }
    ]
  }
]

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Response

List inventory sources

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

enum<string>

required

Execution type

Available options:

AGENT,

MANAGED_SALES_AGENT,

LINKED_STOREFRONT,

MODULAR_SOURCE

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))$

connectionType

enum<string>

Public connection family for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:

AD_SERVER

adServerProvider

enum<string>

Ad-server provider for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:

citrusad

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)

Show child attributes

managedSa

object | null

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

Show child attributes

linkedStorefront

object | null

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.

Show child attributes

reportingType

enum<string> | null

How the underlying agent reports delivery (WEBHOOK, BUCKET, POLLING). Mirrors the AdCP-spec values used when connecting the source. Projected from storefront_agent_source; 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 storefront_agent_source; 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.

agentCapabilityUid

string<uuid> | null

Explicit reusable SALES Agent capability connected to this Source. Null means the Source requires governed connection reconciliation; endpoint similarity is never used.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

declaredAgentProductMode

enum<string> | null

The backing Agent completeness contract. Managed ESA and initial modular Sources project their fixed WHOLESALE contract.

Available options:

WHOLESALE,

COMPOSING,

BOTH

bindingProductMode

enum<string> | null

Source product-path selection only when the Agent declares BOTH; null for single-mode Agents.

Available options:

WHOLESALE,

COMPOSING,

BOTH

effectiveProductMode

enum<string> | null

Effective mode for new discovery. Null when the explicit Agent connection or declaration is unresolved.

Available options:

WHOLESALE,

COMPOSING,

BOTH

productModeReasons

enum<string>[]

Bounded reconciliation reasons when effective mode cannot be resolved.

Available options:

SOURCE_NOT_ACTIVE,

AGENT_BINDING_MISSING,

AGENT_MODE_UNDECLARED,

BOTH_SELECTION_REQUIRED,

MERCHANDISING_ACCESS_INACTIVE,

WHOLESALE_CATALOG_NOT_READY

productPaths

object[]

Readiness for the Agent-supplied and Storefront-built product paths. BOTH exposes both entries; neither path silently replaces the other.

Show child attributes

⌘I