Respond API

Decision Flows list view in the Kaireon Studio — The decision flow whose outcomes /respond records.

POST /api/v1/respond

Records the outcome of a recommendation delivered via the Recommend API. Outcomes feed into behavioral metrics, adaptive model training, experiment analysis, and attribution.

Data plane. This endpoint is part of the public data plane — the runtime decisioning loop (/recommend, /respond, /respond/bulk, /capture) — and is callable with any krn_ API key, including default keys minted without scopes. Management endpoints, by contrast, require control-plane access (see API Keys).

Minimal Request (Recommended)

The smallest way to record an outcome — 5 fields. The system resolves the offer, creative, and channel from the recommendation record. idempotencyKey is required on every call (a request without it is rejected with 400).

{
  "customerId": "CUST001",
  "recommendationId": "rec_7f3a2b1c-9d4e-5f6a-8b7c-0d1e2f3a4b5c",
  "rank": 1,
  "outcome": "click",
  "idempotencyKey": "click-cust001-rank1-1710590400"
}

Full Request (all optional fields)

{
  "customerId": "CUST001",
  "recommendationId": "rec_7f3a2b1c-9d4e-5f6a-8b7c-0d1e2f3a4b5c",
  "rank": 1,
  "outcome": "click",
  "idempotencyKey": "click-cust001-offer001-1710590400",
  "creativeId": "creative_001",
  "offerId": "offer_001",
  "channelId": "channel_email",
  "direction": "outbound",
  "context": {
    "source": "email_campaign_q1",
    "utm_medium": "email"
  },
  "outcomeDetails": {
    "product_sku": "SKU-12345"
  },
  "timestamp": "2026-03-16T14:35:00.000Z",
  "conversionValue": 149.99
}

Field Reference

Field	Type	Required	Description
`customerId`	string	Yes	The customer who interacted with the recommendation
`recommendationId`	string	Yes*	The `recommendationId` from the Recommend API response. Used with `rank` to resolve the offer automatically
`rank`	integer	Yes*	Which offer from the recommendation (1-based). Combined with `recommendationId` to look up the offer, creative, and channel
`outcome`	string	Yes	The outcome type key (e.g., `"click"`, `"accept"`, `"dismiss"`, `"convert"`, `"renewed"`, `"unsubscribed"`). Must match a registered Outcome Type
`creativeId`	string	No	Explicit Creative ID. Only needed if NOT using `recommendationId` + `rank`
`idempotencyKey`	string	Yes	Required. Unique key to prevent double-counting. Returns 400 if missing. Can also be sent as `Idempotency-Key` header
`interactionId`	string	No	Legacy field — use `recommendationId` instead
`direction`	string	No	Direction of the interaction: `"inbound"` or `"outbound"`. Default is `"inbound"` for most outcome types. For impression-category outcomes (e.g., `impression`, `delivery`), the default is `"outbound"` since those represent platform-initiated contacts
`offerId`	string	No	Offer ID. If omitted, resolved automatically from the creative’s parent offer
`channelId`	string	No	Channel ID. A value passed in the body is used as-is; when omitted it is resolved from the creative’s channel (when `creativeId` is provided). Resolving the channel keeps interaction summaries and contact-policy frequency caps attributed to the correct channel.
`placementId`	string	No	Placement ID. If omitted, resolved from the creative
`rank`	integer	No	The position at which the offer was displayed (1-indexed)
`context`	object	No	Arbitrary context metadata (campaign source, UTM params, etc.)
`outcomeDetails`	object	No	Structured details about the outcome (e.g., product SKU, plan selected)
`timestamp`	string	No	ISO 8601 timestamp of the interaction. Defaults to the current server time
`conversionValue`	number	No	Monetary value of the conversion (used for attribution and revenue reporting)
`attributes`	object	No	Additional attributes (device, browser, etc.). Consumed live by the incremental learners AND persisted into the interaction row’s `context`, so batch `/train` extractors — which read the row’s `context` — see the same features the online path saw. Explicit `context` keys win on collision
`channel`	string	No	Channel name string (stored in context)
`placement`	string	No	Placement name string (stored in context)
`responseTime`	number	No	Time in milliseconds the customer took to respond
`deviceType`	string	No	Device type string (stored in context)

Fields marked Yes* require at least one resolution path. You must provide either creativeId OR recommendationId + rank to identify the offer. The field outcome is required (the legacy alias interactionType is also accepted).

Prior to this fix, channelId was only resolved when offerId was missing, causing per-channel frequency caps to be silently broken.

Attribution — how `recommendationId` + `rank` resolves the offer

When recommendationId and rank are supplied (without a direct creativeId), the route looks up the original recommendation through a three-tier ladder. Tiers run in order; the first match wins.

Tier	How it matches	When it applies
1 — column match	`recommendationId` column = supplied value AND `rank` = supplied value	Recommendation rows written after the 2026-06-07 fix. The dedicated column index makes this the fastest and most precise path; a concurrent call for the same customer at the same rank cannot cross-attribute.
2 — legacy JSON match	`response->>'interactionId'` = supplied `recommendationId` AND `rank` = supplied value	Recommendation/impression rows written before the fix, when the interaction ID was stored only inside the `response` JSONB. Rank is still filtered — the stored rank matches exactly what `/recommend` returned, so keeping the clause cannot drop a legitimate match.
3 — rank-only fallback	Most recent `recommendation` or `impression` row for `customerId + rank`	Reached only when tiers 1 and 2 both miss (e.g. a row exists but carries no `recommendationId` in either the column or the JSONB). Callers that never send `recommendationId`, and callers that supply `creativeId` directly, skip all three tiers.

If none of the three tiers resolve a row, the route returns 400 No recommendation found for customer=… rank=…. Limitation: multi-placement /recommend responses return a recommendationId in the response body but write no interaction_history rows (pre-existing behaviour). Precise tier-1 attribution therefore applies to single-flow recommendations and auto-impressions only. Multi-placement callers should supply creativeId directly.

Idempotency

Every call to the Respond API requires an idempotency key to prevent duplicate outcome recording. You can provide it in two ways:

Request body: "idempotencyKey": "unique-key-here"
HTTP header: Idempotency-Key: unique-key-here

If both are provided, the body value takes precedence. When a duplicate key is detected, the API returns the original record with "status": "already_recorded" and a 200 status code (not 201).

recorded_without_adaptation (200). A positive outcome for a (customer, offer, creative) combination that has no matching recommendation and no recent impression (a 30-day lookback) is still written, but adaptive-model training is skipped so a phantom positive can’t inflate attribution past delivery. In that case the response is { "ok": true, "status": "recorded_without_adaptation", "interactionId": "…", "warning": "…" } with a 200 status. Impression/neutral/negative outcomes are unaffected.GET /api/v1/recommend now writes the same recommendation and impression rows as POST and returns interactionId/recommendationId, so outcomes for GET-served recommendations attribute normally — GET-driven traffic no longer lands in recorded_without_adaptation when you close the loop with recommendationId + rank.

Model adaptations — attributed to the model that decided

Per-offer/category/channel/direction/global model adaptations (the propensity-learning rows the scorer reads back — see Adaptive Learning) are written for exactly one model: the model that produced the decision. The target model is resolved from the delivery row’s recorded modelId; if no delivery row for this (customer, offer) carries a model attribution, no adaptation rows are written at all, rather than fanning the outcome out to every active model. Models are isolated — one model’s outcome stream can no longer shift another model’s scores through shared adaptation cells. Separately, per-outcome incremental model-state updates still apply to every active incremental-type model (bayesian, thompson_bandit, epsilon_greedy, online_learner), using the request’s attributes as the feature bag. For bandits configured with armScope: "offer_channel", the outcome’s channelId selects the arm — the update lands on <offerId>:<channelId> so channel-specific stats accumulate separately (see How Scoring Works §6c).

Response: New Record (201)

The response includes enriched names for easy display without additional lookups.

{
  "interactionId": "550e8400-e29b-41d4-a716-446655440000",
  "recommendationId": "c6184851-54f8-49df-88e3-0b11ed3b9fcb",
  "customerId": "CUST-00500",
  "outcome": "click",
  "classification": "positive",
  "rank": 4,
  "offerName": "Multi-Policy Bundle",
  "creativeName": "Multi-Policy Bundle — Email",
  "channelName": "Email Campaign",
  "categoryName": "Policy Renewal",
  "status": "recorded",
  "timestamp": "2026-03-16T14:35:00.000Z"
}

Response: Duplicate (200)

When the same idempotencyKey is sent again:

{
  "interactionId": "550e8400-e29b-41d4-a716-446655440000",
  "recommendationId": "c6184851-54f8-49df-88e3-0b11ed3b9fcb",
  "customerId": "CUST-00500",
  "outcome": "click",
  "status": "already_recorded",
  "timestamp": "2026-03-16T14:35:00.000Z"
}

Outcome Types

Outcomes must be registered in the platform before they can be recorded. Each outcome type has a classification that drives downstream behavior:

Classification	Effect	Examples
`positive`	Increments positive counters, triggers attribution, updates adaptive models with reward	`click`, `accept`, `convert`, `purchase`
`negative`	Increments negative counters, updates models with penalty	`dismiss`, `not_interested`, `unsubscribe`
`neutral`	Tracked but does not affect scoring	`impression`, `view`, `requested_info`

Examples

Record an Impression

curl -X POST https://playground.kaireonai.com/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -H "X-API-Key: krn_your_api_key" \
  -d '{
    "customerId": "CUST001",
    "creativeId": "creative_001",
    "outcome": "impression",
    "idempotencyKey": "imp-cust001-creative001-20260316-1430",
    "interactionId": "550e8400-e29b-41d4-a716-446655440000",
    "rank": 1
  }'

Record a Click

curl -X POST https://playground.kaireonai.com/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -H "X-API-Key: krn_your_api_key" \
  -d '{
    "customerId": "CUST001",
    "creativeId": "creative_001",
    "outcome": "click",
    "idempotencyKey": "click-cust001-creative001-20260316-1435",
    "interactionId": "550e8400-e29b-41d4-a716-446655440000",
    "context": {
      "source": "email_hero_banner"
    }
  }'

Record a Conversion with Value

curl -X POST https://playground.kaireonai.com/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -H "X-API-Key: krn_your_api_key" \
  -d '{
    "customerId": "CUST001",
    "creativeId": "creative_001",
    "outcome": "convert",
    "idempotencyKey": "conv-cust001-offer001-20260316",
    "interactionId": "550e8400-e29b-41d4-a716-446655440000",
    "offerId": "offer_001",
    "conversionValue": 299.99,
    "outcomeDetails": {
      "plan": "platinum",
      "term_months": 12
    }
  }'

Error Responses

Status	Cause
`400`	Missing required fields (`customerId`, `creativeId`/`treatmentId` or `recommendationId`+`rank`, `outcome`/`interactionType`, `idempotencyKey`), unknown outcome type, no recommendation found for the supplied `recommendationId`+`rank`, or invalid JSON
`401`	Missing, invalid, revoked, or expired API key (the key must start with `krn_`)
`403`	The resolved tenant does not exist, or the CSRF guard rejected the request (an API-key `POST` without `Content-Type: application/json` or `X-Requested-With`)
`404`	Creative not found or belongs to another tenant
`415`	`Content-Type` header is not `application/json`
`429`	Rate limit exceeded (1,000 requests per 60s per tenant)
`500`	Internal server error

Example error (unknown outcome type):

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Unknown outcome type: \"purchased\". Register it in Outcome Types first.",
    "status": 400,
    "recommendationId": "d4e5f678-90ab-cdef-1234-567890abcdef",
    "timestamp": "2026-03-16T14:35:00.000Z"
  }
}

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

POST /api/v1/respond

Minimal Request (Recommended)

Full Request (all optional fields)

Field Reference

Attribution — how `recommendationId` + `rank` resolves the offer

Idempotency

Model adaptations — attributed to the model that decided

Response: New Record (201)

Response: Duplicate (200)

Outcome Types

Examples

Record an Impression

Record a Click

Record a Conversion with Value

Error Responses

​POST /api/v1/respond

​Minimal Request (Recommended)

​Full Request (all optional fields)

​Field Reference

​Attribution — how recommendationId + rank resolves the offer

​Idempotency

​Model adaptations — attributed to the model that decided

​Response: New Record (201)

​Response: Duplicate (200)

​Outcome Types

​Examples

​Record an Impression

​Record a Click

​Record a Conversion with Value

​Error Responses

POST /api/v1/respond

Minimal Request (Recommended)

Full Request (all optional fields)

Field Reference

Attribution — how `recommendationId` + `rank` resolves the offer

Idempotency

Model adaptations — attributed to the model that decided

Response: New Record (201)

Response: Duplicate (200)

Outcome Types

Examples

Record an Impression

Record a Click

Record a Conversion with Value

Error Responses