Channels API

See also: Channels concept and configuration for what this API powers, when to call it, and how it is configured.

Channels define how recommendations are delivered to customers. Each channel has a delivery mode, optional provider configuration, and can contain multiple placements (slots where creatives are rendered). All channels support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).

See the Channels feature page for UI guidance and conceptual overview.

Base path

/api/v1/channels

List channels

GET /api/v1/channels

Returns a paginated list of channels for the current tenant, ordered by creation date (newest first). Each channel includes its placements and creatives. By default, soft-deleted channels are excluded.

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Maximum results per page. Default `50`, max `100`.
`cursor`	No	string	Cursor for keyset pagination. Pass the last `id` from the previous page.
`includeDeleted`	No	string	Set to `"true"` to include soft-deleted channels in the results.

Response `200`

{
  "data": [
    {
      "id": "ch_email",
      "tenantId": "t_001",
      "name": "Email",
      "channelType": "email",
      "status": "active",
      "description": "Transactional and marketing email channel.",
      "deliveryMode": "api",
      "impressionMode": "explicit",
      "couplingMode": "partial",
      "providerConfig": { "provider": "sendgrid" },
      "fileConfig": {},
      "version": 1,
      "deletedAt": null,
      "placements": [
        {
          "id": "pl_hero",
          "name": "Hero Banner",
          "slotType": "banner",
          "maxSlots": 1
        }
      ],
      "creatives": [],
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "cursor": null,
    "hasMore": false,
    "total": 5
  }
}

Error codes

Code	Reason
`401`	Missing or invalid API key / session.
`403`	Insufficient role.

Create a channel

POST /api/v1/channels

Creates a new channel. You can inline placements in the create request to set them up atomically. Creating a channel also auto-creates flow routes to the default decision flow for each placement.

Request body

Field	Required	Type	Description
`name`	Yes	string (1-255)	Unique channel name.
`channelType`	No	string	Channel type identifier. Default `"email"`.
`status`	No	enum	`draft` (default), `active`, `paused`, `archived`.
`description`	No	string	Channel description.
`deliveryMode`	No	enum	`api` (default), `file`, `integration`, `manual`.
`impressionMode`	No	enum	`explicit` (default), `implicit`.
`couplingMode`	No	enum	`partial` (default) or `atomic`. Controls within-channel placement coupling — when `atomic`, an empty placement on this channel causes ALL placements on the channel to come back empty in the Recommend response. Used for composite surfaces (email body, push notification) where a partial response renders broken. Cross-channel coupling is intentionally not supported. See Placement Coupling in the composable pipeline docs.
`providerConfig`	No	object	Provider-specific configuration.
`fileConfig`	No	object	Deprecated — batch file output now lives on the campaign (`Run.fileConfig`; see File Output Configuration). Still accepted/stored for backward compatibility and validated when non-empty, but the batch executor no longer reads it.
`placements`	No	array	Inline placement definitions (see below).

Placement object (inline)

Field	Required	Type	Description
`name`	Yes	string	Placement name.
`description`	No	string	Placement description.
`slotType`	No	string	Slot type (e.g., `banner`, `card`, `inline`). Default `"banner"`.
`maxSlots`	No	integer (>= 1)	Maximum concurrent slots. Default `1`.
`schema`	No	object	Content schema for the slot.
`targeting`	No	object	Targeting rules for the placement.

Example request

{
  "name": "Mobile Push",
  "channelType": "push",
  "deliveryMode": "api",
  "impressionMode": "implicit",
  "providerConfig": { "provider": "firebase" },
  "placements": [
    {
      "name": "Notification Tray",
      "slotType": "notification",
      "maxSlots": 3
    }
  ]
}

Response `201`

Returns the created channel with placements, creatives relations, version: 1, and deletedAt: null. An audit log entry is created with a create action.

Error codes

Code	Reason
`400`	Validation error.
`401`	Missing or invalid API key / session.
`403`	Insufficient role (requires `editor` or `admin`).
`409`	A channel with that name already exists.
`413`	Request body exceeds the 2 MB limit.
`415`	`Content-Type` is not `application/json`.

Update a channel

PUT /api/v1/channels

Updates an existing channel. Only provided fields are changed. Placements are managed separately via the Placements API. The version field is auto-incremented and a before/after audit snapshot is recorded.

Request body

Field	Required	Type	Description
`id`	Yes	string	Channel ID to update.
`name`	No	string (1-255)	Updated name.
`channelType`	No	string	Updated type.
`status`	No	enum	`draft`, `active`, `paused`, `archived`.
`description`	No	string	Updated description.
`deliveryMode`	No	enum	`api`, `file`, `integration`, `manual`.
`impressionMode`	No	enum	`explicit`, `implicit`.
`couplingMode`	No	enum	`partial` or `atomic`. See create section above for behavior.
`providerConfig`	No	object	Updated provider config.
`fileConfig`	No	object	Deprecated — file output is configured on the campaign (`Run.fileConfig`); accepted for backward compatibility but not read by the batch executor.

Example request

{
  "id": "ch_push",
  "status": "active",
  "providerConfig": { "provider": "firebase", "apiKey": "***" }
}

Response `200`

Returns the updated channel object with the incremented version.

Error codes

Code	Reason
`400`	Validation error.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.
`404`	No channel with that `id` (or name) in your tenant.
`409`	A channel with that name already exists.
`413`	Request body exceeds the 2 MB limit.
`415`	`Content-Type` is not `application/json`.

Delete a channel (soft-delete)

DELETE /api/v1/channels?id={channelId}

Soft-deletes a channel by setting its deletedAt timestamp. Cascade behavior: all associated placements and creatives are also soft-deleted. The version is incremented on the channel and each cascaded child. An audit log entry is recorded for every affected entity.

Query parameters

Parameter	Required	Type	Description
`id`	Yes	string	Channel ID to delete.

Response `200`

{
  "success": true,
  "cascaded": 4
}

The cascaded field indicates how many child entities (placements + creatives) were also soft-deleted.

Error codes

Code	Reason
`400`	Missing `id` query parameter, or the channel is already deleted.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.
`404`	No channel with that `id` (or name) in your tenant.

To restore a soft-deleted channel, use POST /api/v1/restore?entityType=channel&id={channelId} (admin only). Restoring a channel does not automatically restore cascaded placements or creatives — you must restore them individually.

Role requirements

Method	Minimum role
GET	`viewer`
POST	`editor`
PUT	`editor`
DELETE	`editor`

Channels

Learn more about creating and managing channels in the platform UI.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base path

List channels

Query parameters

Response `200`

Error codes

Create a channel

Request body

Placement object (inline)

Example request

Response `201`

Error codes

Update a channel

Request body

Example request

Response `200`

Error codes

Delete a channel (soft-delete)

Query parameters

Response `200`

Error codes

Role requirements

Channels

​Base path

​List channels

​Query parameters

​Response 200

​Error codes

​Create a channel

​Request body

​Placement object (inline)

​Example request

​Response 201

​Error codes

​Update a channel

​Request body

​Example request

​Response 200

​Error codes

​Delete a channel (soft-delete)

​Query parameters

​Response 200

​Error codes

​Role requirements

Channels

Base path

List channels

Query parameters

Response `200`

Error codes

Create a channel

Request body

Placement object (inline)

Example request

Response `201`

Error codes

Update a channel

Request body

Example request

Response `200`

Error codes

Delete a channel (soft-delete)

Query parameters

Response `200`

Error codes

Role requirements