> ## 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

> Author and manage named slots — like hero_banner, sidebar_widget, checkout_upsell — that creatives target inside each channel.

<Note>
  **See also**: [Placements REST API reference](/api-reference/placements) for request/response shapes, status codes, and error semantics.
</Note>

A **Placement** is a named slot inside a [Channel](/studio/channels) where a recommendation can appear — for example `hero_banner` on a web channel, `checkout_upsell` on an in-app channel, or `welcome_email_top` on an email channel. Creatives target a specific placement, and the decision engine allocates one creative per requested placement at decision time.

Placements give you fine-grained control over **where** content lands on a surface without needing to invent a separate channel for each slot.

***

## The Placements page

Path: `/studio/placements`

The studio page is a standard two-panel layout:

* **Left:** list of all placements in the tenant with name, channel, key, status, and last-update timestamp.
* **Right:** detail form for the selected row, or a blank create form when **+ New Placement** is clicked.

### Fields

| Field           | Required | Description                                                                                                                                                |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Channel**     | Yes      | The parent channel this placement belongs to. A placement is scoped to exactly one channel.                                                                |
| **Name**        | Yes      | Human-readable label shown in the studio (e.g. "Hero Banner").                                                                                             |
| **Key**         | Yes      | Machine-readable identifier used in the Recommend API (e.g. `hero_banner`). Lowercase + underscores recommended; must be unique within the parent channel. |
| **Description** | No       | Free-text note describing where the placement appears and what it's for.                                                                                   |
| **Status**      | No       | `active` (default) or `inactive`. Inactive placements are excluded from candidate matching.                                                                |

### Creating a placement

1. Open `/studio/placements`.
2. Click **+ New Placement**.
3. Pick a channel, give it a name + key, and click **Save**.
4. Linked creatives can now target this placement via their `placementKey` field.

### Editing a placement

Click any row in the list. The right pane switches to edit mode with the current values pre-filled. Click **Save** to apply, or **Delete** to soft-delete the placement (associated creatives are not deleted but will no longer match decisions for the removed placement key).

***

## How placements are used at decision time

When the [Recommend API](/api-reference/recommend) request specifies a placement (via the `placements` array), the decision engine narrows the candidate set to creatives whose `placementKey` matches. If no placement is specified, every active placement within the requested channel is eligible.

See [Channels — How channels work](/studio/channels#how-channels-work) for the full delivery pipeline.

***

## API

All operations are available via the REST API as well — see [api-reference/placements](/api-reference/placements) for request/response details and role requirements.