Create a modular source from a feed

POST /api/v2/storefront/inventory-sources/modular/feed Creates a real MODULAR_SOURCE for sellers who manage availability through a spreadsheet, export, or manual feed rather than a live ad-server integration. The source is created with the built-in avails-feed module and booking ledger. When execution.mode is omitted, it defaults to manual and also receives the provider-neutral manual execution module. Buyer media buys then create seller work items for upstream booking, creative handoff, and final reporting instead of requiring a provider-specific adapter. In a /mcp/v3 seller session, call open_page with {"page":"modular_source_setup"}. This opens the portable Add a modular source Task. After the seller reviews and confirms the form, the app calls create_feed_modular_inventory_source, which performs the same production write described on this page and opens the new source workspace. create_feed_modular_inventory_source is an app-only completion operation: an MCP host may expose it to the embedded Task, but it is not intended for the model to call directly. The same completion operation is available to this portable Task when a storefront MCP host renders it. The operation and its Task are listed only for sellers on Premium or Enterprise with the Merchandising profile. Basic sellers should use the standard inventory-feed setup available in their storefront instead. This endpoint does not attach arbitrary provider execution, reporting, creative, or OMS adapters. upstream_system details remain non-secret setup metadata until a matching provider module exists.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/inventory-sources/modular/feed \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "reachafrica-ctv",
    "name": "ReachAfrica CTV Avails",
    "availsSource": {
      "type": "spreadsheet",
      "cadence": "monthly",
      "description": "Seller uploads monthly South Africa CTV avails"
    },
    "booking": {
      "mode": "booking_ledger"
    },
    "execution": {
      "mode": "manual",
      "systemName": "Seller ops"
    },
    "reporting": {
      "mode": "upload",
      "sampleAvailable": true
    },
    "creative": {
      "mode": "manual",
      "notes": "Human review confirms broadcast specs"
    }
  }'

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Seller-facing source name, 1-255 characters
`sourceId`	string	No	Storefront-scoped ID. Lowercase letters, numbers, dashes, or underscores only. Defaults to a slugified `name`
`includeBookingLedger`	boolean	No	Defaults to `true`. Setting it to `false` requires an explicit non-manual execution mode and leaves the source non-bookable until compatible modules are attached
`availsSource.type`	enum	No	`upload`, `spreadsheet`, `api`, `manual`, or `unknown`
`availsSource.cadence`	string	No	Human-readable update cadence, such as `monthly`
`availsSource.description`	string	No	Non-secret feed description
`booking.mode`	enum	No	`booking_ledger`, `manual`, or `upstream_oms`
`booking.systemName`	string	No	Non-secret OMS or booking system name
`booking.notes`	string	No	Non-secret booking notes
`execution.mode`	enum	No	`manual`, `upstream_system`, or `none`. Defaults to `manual`, which attaches the execution workflow required to finalize bookings
`execution.systemName`	string	No	Non-secret execution system name
`reporting.mode`	enum	No	`upload`, `manual`, `upstream_export`, `api`, or `none`
`reporting.systemName`	string	No	Non-secret reporting system name
`reporting.sampleAvailable`	boolean	No	Whether the seller has provided or can provide a sample report export
`creative.mode`	enum	No	`manual`, `upstream_system`, or `none`
`creative.systemName`	string	No	Non-secret creative workflow system name
`notes`	string	No	Non-secret setup notes

Do not send secrets in this request. API keys, login credentials, private keys, and service-account files must use the appropriate credential flow for the module or ad-server connection.

Response

201 Created with the new source id and modular runtime projection:

{
  "inventorySourceId": "900222",
  "sourceId": "reachafrica-ctv",
  "projection": {
    "inventorySource": {
      "id": "900222",
      "sourceId": "reachafrica-ctv",
      "name": "ReachAfrica CTV Avails",
      "executionType": "MODULAR_SOURCE",
      "status": "ACTIVE",
      "healthStatus": "healthy"
    },
    "modules": [
      {
        "moduleInstanceId": "static-avails-feed",
        "kind": "INVENTORY_FEED",
        "provider": "agentic",
        "status": "ACTIVE"
      },
      {
        "moduleInstanceId": "booking-ledger",
        "kind": "BOOKING_LEDGER",
        "provider": "agentic",
        "status": "ACTIVE"
      },
      {
        "moduleInstanceId": "manual-execution",
        "kind": "TRAFFICKING",
        "provider": "agentic",
        "status": "ACTIVE"
      }
    ],
    "activeAvailCount": 0,
    "openWorkItemCount": 0
  }
}

After creating the source, upload or paste avails into POST /api/v2/storefront/inventory-sources/{sourceId}/modular/avails-feed. Preview normalized rows first, then commit only after confirming row grain and net sellable capacity. If execution.mode is explicitly upstream_system or none, the response includes a NO_EXECUTION_MODULE warning. The source cannot finalize buyer bookings until a compatible trafficking module is attached. Because there is currently no self-service attach flow, choose manual before uploading availability unless an operator is provisioning that provider module.

Errors

400 VALIDATION_ERROR — missing name or invalid sourceId.
401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — the caller does not have a storefront.
409 CONFLICT — another active source already uses the same sourceId.

See Errors for the full error contract.

Modular lifecycle

How feed, booking, HITL, and reporting stages fit together

Get modular readiness

Inspect modules and lifecycle status

Update module config

Update non-secret module setup

Inventory source tasks

All operations

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create a modular source from a feed

Request

Parameters

Response

Errors

Modular lifecycle

Get modular readiness

Update module config

Inventory source tasks

​Request

​Parameters

​Response

​Errors

​Related

Modular lifecycle

Get modular readiness

Update module config

Inventory source tasks

Request

Parameters

Response

Errors

Related