Respond Bulk

Record up to 1000 customer outcomes in one request with per-item idempotency, partial-success reporting, and outbox-backed event delivery

POST /api/v1/respond/bulk records multiple outcome events in a single round trip and returns a per-item success/failure manifest. The route is designed for batch loaders, file imports, and replay tools that need to ingest historical conversions without the per-call overhead of POST /api/v1/respond.

What it does

The endpoint accepts an outcomes: [...] array of 1 to 1000 items. Each item is processed sequentially in batches of 50. Per-item logic mirrors the singular /respond route: outcome-type lookup, creative resolution for channelId and placementId, offer existence check, idempotency-key check, then a single database transaction that records one interaction-history row plus one outcome.recorded outbox event.

A failed item never aborts the batch — the response accumulates an errors[] array of { index, error } entries and continues. The response status is 200 when at least one item succeeded and 422 when every item failed. Per-item summary aggregation runs as fire-and-forget after the transaction commits.

Quick start

curl -X POST https://playground.kaireonai.com/api/v1/respond/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: krn_your_api_key" \
  -H "X-Tenant-Id: 5a9904b9-..." \
  -d '{
    "outcomes": [
      {
        "customerId": "cust_42",
        "offerId": "off_premium_card",
        "creativeId": "crv_email_a",
        "outcome": "click",
        "timestamp": "2026-04-30T10:15:00Z",
        "context": { "device": "mobile" }
      },
      {
        "customerId": "cust_99",
        "offerId": "off_savings_acct",
        "outcome": "convert",
        "conversionValue": 250.00,
        "idempotencyKey": "import-batch-2026-04-30:line-7"
      }
    ]
  }'

Response (mixed success):

{
  "processed": 2,
  "succeeded": 1,
  "failed": 1,
  "errors": [
    { "index": 1, "error": "Offer not found" }
  ]
}

How it works

Authentication and rate limiting

Every call goes through the same tenant-resolution layer as /recommend. After tenant resolution, the handler applies a per-tenant rate-limit window — 100 requests per 60 seconds for playground tenants and 1000 requests per 60 seconds for non-playground tenants. The rate limiter runs in fail-closed mode — when the limiter backend is unreachable the request is rejected rather than allowed through.

Validation

The request body is validated server-side and rejected with 400 Bad Request when any of the following are violated:

• outcomes length is between 1 and 1000.
• Each item must include customerId, offerId, and outcome as non-empty strings.
• direction, if supplied, must be "inbound" or "outbound".
• conversionValue, when supplied, must be a number.

Outcome-type lookup

Outcome types are loaded once for the whole batch. When an item names an outcome that is not registered for the tenant, the per-item error is Unknown outcome type: "<key>" and the item is skipped (the rest of the batch continues).

Idempotency

Each item gets an idempotencyKey. If the caller supplied one it is used verbatim; otherwise the endpoint synthesizes one from customerId + offerId + creativeId + outcomeKey + 5-minute time bucket. The deduplication identifier is customerId:offerId:creativeId:outcomeKey:idempotencyKey.

Inside the per-item transaction, the endpoint first checks for an existing interaction-history row with the same idempotency key for the tenant. When a row already exists, the item is reported as succeeded without a duplicate insert.

Outbox-backed event delivery

After each successful insert, the same transaction writes one outcome.recorded outbox event — the event row is durable in the same commit as the interaction row. The dedicated outbox publisher then picks the row up and delivers to the configured event-publisher backend. See Outbox publisher.

Conversion value resolution

When conversionValue is omitted and the outcome’s classification is "positive", the endpoint falls back to the offer’s businessValue. For neutral or negative outcomes the conversion value stays 0.

Audit log

A single bulk_create audit entry summarizing { processed, succeeded, failed } is written after the loop completes. Per-item entries are not created — the audit chain records the batch as one unit.

Reference

Request body

outcomes · array · required

Array of 1 to 1000 outcome items.

outcomes[] per-item shape

customerId · string · required

Customer identifier the outcome is attributed to.

offerId · string · required

Offer identifier the outcome targets. Must exist for the tenant or the item is rejected with Offer not found.

outcome · string · required

Outcome type key. Must match an outcome-type key registered for the tenant via /api/v1/outcome-types.

creativeId · string

Optional creative identifier. When supplied, the endpoint auto-resolves channelId and placementId from the creative. Required for impression-class outcomes that need channel attribution.

channelId · string

Channel identifier. Defaults to the creative’s channelId when creativeId is supplied.

placementId · string

Placement identifier. Defaults to the creative’s placementId when creativeId is supplied.

channel · string

Channel name passed through to interaction.context.channel for analytics filters. Not used for routing.

placement · string

Placement name passed through to interaction.context.placement.

timestamp · string

ISO timestamp the outcome occurred. Defaults to the current server time when omitted.

idempotencyKey · string

Operator-supplied idempotency key. When omitted the endpoint synthesizes one from customerId + offerId + creativeId + outcomeKey + 5-minute time bucket.

context · object

Free-form context merged into the recorded interaction.context JSON. The endpoint always adds bulk: true so consumers can distinguish bulk-imported events.

outcomeDetails · object

Free-form details merged into the recorded interaction.outcome JSON alongside conversionValue.

conversionValue · number

Monetary value of the outcome. Falls back to the offer’s businessValue for positive outcomes when omitted.

direction · string

"inbound" or "outbound". Defaults to "outbound" for impression-category outcomes and "inbound" for everything else.

Response

processed · number

Total items in the request body — equals outcomes.length.

succeeded · number

Items that produced a new interaction-history insert OR were idempotency-deduplicated against an existing row.

failed · number

Items that produced an error. Per-item details are in errors[].

errors · array

Present only when failed > 0. Each entry: { index: number, error: string }. index is the 0-based position in the request outcomes[] array.

Status codes

Code	When
200	At least one item succeeded
400	Invalid JSON body or schema validation failure
401	Missing tenant context
403	Invalid tenant identifier
422	Every item in the batch failed
429	Rate limit exceeded
500	Unexpected error before the per-item loop

Required headers

Header	Required	Purpose
Content-Type	Yes	application/json
X-API-Key	Yes (one of the two)	API key (krn_…)
X-Tenant-Id	Yes (one of the two)	Direct tenant id

Configuration

Environment variables

Variable	Effect
NODE_ENV=test	Disables rate limiting in the test runner

The endpoint reads no other environment variables directly. The downstream outbox publisher reads OUTBOX_LIVENESS_FILE and the outbox-reaper cron reads OUTBOX_REAPER_STALENESS_SECONDS.

Limits

Setting	Value
Maximum items per request	1000
Chunk size for sequential processing	50
Rate limit (playground tenants)	100 / 60s
Rate limit (non-playground)	1000 / 60s

Honest limits

• Per-item processing is sequential, not parallel. A 1000-item batch produces up to 1000 sequential database transactions — wall time scales linearly with batch size. Sustained throughput is bounded by Postgres write contention, not API replicas.
• Per-customer/offer summary aggregation runs fire-and-forget after each transaction commits. When the call rejects, the warning is logged but the item still counts as succeeded. Aggregate counters may briefly lag the underlying interaction rows.
• The endpoint does not expose a dryRun flag. To validate a batch shape without writing, the caller has to send a single-item request and discard the result.
• The errors[] array is included only when failed > 0. Callers checking response.errors.length must handle the missing-field case.
• An idempotency-deduplicated item is reported as succeeded, not as a separate counter. Callers cannot distinguish “newly recorded” from “already recorded” from the response alone.

Related

• Respond API — single-outcome endpoint with the same per-item contract.
• Outcome Types — register the outcome keys this endpoint validates against.
• Outbox publisher — delivers the outcome.recorded events written by this endpoint.
• Cron tier — runs /api/v1/cron/outbox-reaper to recover stuck outbox rows.