---
title: "Create a placement"
method: POST
path: "/v25-10-beta/agentic-logic/placements"
tags: ["Agentic Logic"]
---

# Create a placement

`POST /v25-10-beta/agentic-logic/placements`

## Request

- Base URL: `https://api.intelligems.io`
- URL: `https://api.intelligems.io/v25-10-beta/agentic-logic/placements`
- Auth: API key in header `intelligems-access-token`
- TypeScript: <https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/docs/v25-10-beta/agentic-logic/placements/post.ts> (a function with typed inputs; its response is checked against the schema)

```http
POST /v25-10-beta/agentic-logic/placements
```

Creates a placement — a named slot on a surface that rules serve into.

- `name` (string, required) — Merchant-facing placement name.
- `surface` (string, required) — `onsite`, `checkout`, or `post-purchase`.
  Fixed at creation.

The returned `placement.id` is the `placementId` used by evaluation requests.

Use the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.

**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.

## Request body

- object: Create a placement. The response's server-issued id is the wire `placementId`.
  - `name` string, required: Merchant-facing placement name.
  - `surface` 'onsite' | 'checkout' | 'post-purchase', required: Surface the placement renders on. Fixed at creation.

## Response `200`

OK

- object
  - `placement` object, required: One placement: a server-issued addressable location a surface renders recommendations into. The placement's id IS the `placementId` requests and impressions carry.
    - `id` string, required: Server-issued placement id (uuid). Wire identity — never renamed or reused.
    - `organizationId` string, required: Owning organization id (uuid).
    - `name` string, required: Merchant-facing placement name.
    - `surface` 'onsite' | 'checkout' | 'post-purchase', required: Surface the placement renders on ('onsite' | 'checkout' | 'post-purchase'). Fixed at creation — a new surface is a new placement.
    - `createdAtTs` number, required: Creation time, Unix epoch-ms.
    - `lastUpdateTs` number, required: Last update time, Unix epoch-ms.
    - `lastSeenAtTs` number, nullable, required: Liveness: when a real shopper request for this placement last reached the engine (Unix epoch-ms), or null if none has within the retention window. Only the `serving` lane beats it — previews and API evaluations never do — so it answers 'is this placement actually live on the storefront', not 'did it render products'. Best-effort and TTL-bounded; never a billing or analytics source.

## Other responses

- `429`: Too Many Requests

---

[API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)