> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a modular source from a feed
> Create a modular source for seller-uploaded avails feeds
`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
```bash curl theme={null}
curl -X POST https://api.apostra.com/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:
```json theme={null}
{
"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](/v2/reference/errors) for the full error contract.
## Related
How feed, booking, HITL, and reporting stages fit together
Inspect modules and lifecycle status
Update non-secret module setup
All operations