Placements API

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.

See the Channels feature page for details on how placements work within channel configurations.

Base path

/api/v1/placements

List placements

GET /api/v1/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 `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 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": {
    "limit": 50,
    "cursor": null,
    "hasMore": false,
    "total": 6
  }
}

Create a placement

POST /api/v1/placements

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 — any string is accepted. Common values: `"hero"`, `"banner"` (default), `"sidebar"`, `"modal"`, `"full_screen"`, `"inline"`, `"toast"`.
`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.

Side effects

Creating the first placement on a tenant triggers ensureBaseFlow (lib/decision-flows/base-flow.ts) so a default base-nba-flow exists for routing. The auto-created flow includes a match_creatives node with placementMatchMode: "exact", which means subsequent /api/v1/recommend calls that pass either a single placement or a placements: [...] array filter candidates to creatives whose placementId matches the request — without any flow editing required. See Decision Flow Internals for the full default node order. A flow-route entry is also created automatically, pointing the new (channelId, placementId) combination at the default flow; this is best-effort and silently no-ops if a route already exists.

Error codes

Code	Reason
`400`	Validation error (missing `channelId` or `name`), or a `channelId` that doesn’t exist in your tenant (foreign-key ownership is validated).
`401`	Missing or invalid API key / session.
`403`	Insufficient role (requires `editor` or `admin`).
`409`	A placement with that name already exists.
`413`	Request body exceeds the 2 MB limit.
`415`	`Content-Type` is not `application/json`.

Update a placement

PUT /api/v1/placements

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.
`404`	No placement with that `id` (or name) in your tenant.
`409`	A placement with that name already exists.
`413`	Request body exceeds the 2 MB limit.
`415`	`Content-Type` is not `application/json`.

Delete a placement

DELETE /api/v1/placements?id={placementId}

Soft-deletes a placement by setting its 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`

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base path

List placements

Query parameters

Response `200`

Create a placement

Request body

Example request

Response `201`

Side effects

Error codes

Update a placement

Request body

Response `200`

Error codes

Delete a placement

Query parameters

Response `200`

Error codes

Role requirements

​Base path

​List placements

​Query parameters

​Response 200

​Create a placement

​Request body

​Example request

​Response 201

​Side effects

​Error codes

​Update a placement

​Request body

​Response 200

​Error codes

​Delete a placement

​Query parameters

​Response 200

​Error codes

​Role requirements

Base path

List placements

Query parameters

Response `200`

Create a placement

Request body

Example request

Response `201`

Side effects

Error codes

Update a placement

Request body

Response `200`

Error codes

Delete a placement

Query parameters

Response `200`

Error codes

Role requirements