Skip to main content
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).
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.

​
Query parameters

ParameterRequiredTypeDescription
limitNointegerMaximum results per page. Default 25.
cursorNostringCursor for keyset pagination.

​
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",
      "providerConfig": { "provider": "sendgrid" },
      "fileConfig": {},
      "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": {
    "total": 5,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

​
Create a channel

POST /api/v1/channels
Creates a new channel. You can inline placements in the create request to set them up atomically.

​
Request body

FieldRequiredTypeDescription
nameYesstring (1-255)Unique channel name.
channelTypeNostringChannel type identifier. Default "email".
statusNoenumdraft (default), active, paused, archived.
descriptionNostringChannel description.
deliveryModeNoenumapi (default), file, integration, manual.
impressionModeNoenumexplicit (default), implicit.
providerConfigNoobjectProvider-specific configuration.
fileConfigNoobjectFile delivery configuration (when deliveryMode is file).
placementsNoarrayInline placement definitions (see below).

​
Placement object (inline)

FieldRequiredTypeDescription
nameYesstringPlacement name.
descriptionNostringPlacement description.
slotTypeNostringSlot type (e.g., banner, card, inline). Default "banner".
maxSlotsNointeger (>= 1)Maximum concurrent slots. Default 1.
schemaNoobjectContent schema for the slot.
targetingNoobjectTargeting 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 and creatives relations.

​
Error codes

CodeReason
400Validation error.
409A channel with that name already exists.
415Content-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.

​
Request body

FieldRequiredTypeDescription
idYesstringChannel ID to update.
nameNostring (1-255)Updated name.
channelTypeNostringUpdated type.
statusNoenumdraft, active, paused, archived.
descriptionNostringUpdated description.
deliveryModeNoenumapi, file, integration, manual.
impressionModeNoenumexplicit, implicit.
providerConfigNoobjectUpdated provider config.
fileConfigNoobjectUpdated file config.

​
Example request

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

​
Response 200

Returns the updated channel object.

​
Delete a channel

DELETE /api/v1/channels?id={channelId}
Deletes a channel by ID. This also removes all associated placements.

​
Query parameters

ParameterRequiredTypeDescription
idYesstringChannel ID to delete.

​
Response 204

Empty body on success.

​
Error codes

CodeReason
400Missing id query parameter.

​
Role requirements

MethodMinimum role
GETviewer
POSTeditor
PUTeditor
DELETEeditor

Channels

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