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.
Placements define the slots within a channel where offers can be rendered. Each placement belongs to a channel and specifies the slot type, maximum number of offers, content schema, and targeting rules.
Base path
List placements
Returns a paginated list of placements for the current tenant, ordered alphabetically by name. Each placement includes its parent channel and associated creatives.
Query parameters
| Parameter | Required | Type | Description |
|---|
channelId | No | string | Filter placements by channel. |
limit | No | integer | Maximum results per page. Default 25. |
cursor | No | string | Cursor for keyset pagination. |
includeDeleted | No | string | Set to "true" to include soft-deleted placements. |
Response 200
{
"data": [
{
"id": "pl_001",
"tenantId": "t_001",
"channelId": "ch_web",
"name": "Homepage Hero Banner",
"description": "Full-width banner on the homepage above the fold.",
"slotType": "banner",
"maxSlots": 1,
"schema": {},
"targeting": {},
"channel": {
"id": "ch_web",
"name": "Web",
"channelType": "web"
},
"creatives": [],
"version": 1,
"deletedAt": null
}
],
"pagination": {
"total": 6,
"limit": 25,
"hasMore": false,
"nextCursor": null
}
}
Create a placement
Creates a new placement slot definition.
Request body
| Field | Required | Type | Description |
|---|
channelId | Yes | string | Parent channel ID. |
name | Yes | string (1-255) | Placement name. |
description | No | string | Placement description. Default "". |
slotType | No | string | Slot type (e.g., "banner", "card", "inline", "modal"). Default "banner". |
maxSlots | No | integer (>= 1) | Maximum number of offers in this placement. Default 1. |
schema | No | object | Content schema definition for this placement. Default {}. |
targeting | No | object | Targeting rules for placement eligibility. Default {}. |
Example request
{
"channelId": "ch_web",
"name": "Homepage Hero Banner",
"description": "Full-width banner on the homepage above the fold.",
"slotType": "banner",
"maxSlots": 1,
"targeting": {
"pages": ["homepage"],
"segments": ["high_value"]
}
}
Response 201
Returns the created placement object with channel and creatives relations.
Error codes
| Code | Reason |
|---|
400 | Validation error (missing channelId or name). |
401 | Missing or invalid API key / session. |
403 | Insufficient role (requires editor or admin). |
409 | A placement with that name already exists. |
415 | Content-Type is not application/json. |
Update a placement
Updates an existing placement. Only provided fields are changed.
Request body
| Field | Required | Type | Description |
|---|
id | Yes | string | The placement ID to update. |
name | No | string (1-255) | Updated name. |
description | No | string | Updated description. |
slotType | No | string | Updated slot type. |
maxSlots | No | integer (>= 1) | Updated max slots. |
schema | No | object | Updated content schema. |
targeting | No | object | Updated targeting rules. |
Response 200
Returns the updated placement object with channel and creatives relations.
Error codes
| Code | Reason |
|---|
400 | Validation error. |
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
409 | A placement with that name already exists. |
415 | Content-Type is not application/json. |
Delete a placement
DELETE /api/v1/placements?id={placementId}
deletedAt timestamp. The version is incremented.
Query parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | Placement ID to delete. |
Response 200
{
"success": true,
"cascaded": 0
}
Error codes
| Code | Reason |
|---|
400 | Missing id query parameter, entity not found, or entity already deleted. |
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
To restore a soft-deleted placement, use POST /api/v1/restore?entityType=placement&id={placementId} (admin only).
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | editor |
