Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ParameterRequiredTypeDescription
limitNointegerMaximum results per page. Default 25.
cursorNostringCursor for keyset pagination.
includeDeletedNostringSet 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",
      "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": {
    "total": 5,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

​
Error codes

CodeReason
401Missing or invalid API key / session.
403Insufficient 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

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, creatives relations, version: 1, and deletedAt: null. An audit log entry is created with a create action.

​
Error codes

CodeReason
400Validation error.
401Missing or invalid API key / session.
403Insufficient role (requires editor or admin).
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. The version field is auto-incremented and a before/after audit snapshot is recorded.

​
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 with the incremented version.

​
Error codes

CodeReason
400Validation error.
401Missing or invalid API key / session.
403Insufficient role.
409A channel with that name already exists.

​
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

ParameterRequiredTypeDescription
idYesstringChannel 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

CodeReason
400Missing id query parameter, entity not found, or entity already deleted.
401Missing or invalid API key / session.
403Insufficient role.
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

MethodMinimum role
GETviewer
POSTeditor
PUTeditor
DELETEeditor

Channels

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