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

ParameterRequiredTypeDescription
channelIdNostringFilter placements by channel.
limitNointegerMaximum results per page. Default 25.
cursorNostringCursor for keyset pagination.

​
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": [],
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 6,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

​
Create a placement

POST /api/v1/placements
Creates a new placement slot definition.

​
Request body

FieldRequiredTypeDescription
channelIdYesstringParent channel ID.
nameYesstring (1-255)Placement name.
descriptionNostringPlacement description. Default "".
slotTypeNostringSlot type (e.g., "banner", "card", "inline", "modal"). Default "banner".
maxSlotsNointeger (>= 1)Maximum number of offers in this placement. Default 1.
schemaNoobjectContent schema definition for this placement. Default {}.
targetingNoobjectTargeting 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

CodeReason
400Validation error (missing channelId or name).
415Content-Type is not application/json.

​
Update a placement

PUT /api/v1/placements
Updates an existing placement. Only provided fields are changed.

​
Request body

FieldRequiredTypeDescription
idYesstringThe placement ID to update.
nameNostring (1-255)Updated name.
descriptionNostringUpdated description.
slotTypeNostringUpdated slot type.
maxSlotsNointeger (>= 1)Updated max slots.
schemaNoobjectUpdated content schema.
targetingNoobjectUpdated targeting rules.

​
Response 200

Returns the updated placement object with channel and creatives relations.

​
Error codes

CodeReason
400Validation error.

​
Delete a placement

DELETE /api/v1/placements?id={placementId}
Deletes a placement by ID.

​
Query parameters

ParameterRequiredTypeDescription
idYesstringPlacement ID to delete.

​
Response 204

Empty body on success.

​
Error codes

CodeReason
400Missing id query parameter.

​
Role requirements

MethodMinimum role
GETviewer
POSTeditor
PUTeditor
DELETEeditor