POST /v1/offers/decide

Authentication

Bearer serving key required. Setup tokens are rejected. The app is inferred from the key.

Rate limit

60 requests per minute per client IP. HTTP 429 with `{ ok: false, error: "rate_limited" }`.

Request headers

Request body

Constraints

• message is the current user turn only. Do not send a raw full transcript.
• No personal identity, email, phone, advertising ID, precise location, health, financial, biometric, or cross-app identity data.
• The current message is processed transiently and is not persisted.
• Typed digest is optional and has no free text.
• Unknown consent, age, or safety results in safe no-fill.
• Serving requires audience.age_band = 18_plus and audience.contextual_offer_consent = true.
• native_surface.clickable and native_surface.disclosure_capable are required self-attestation booleans. Either false is CAPABILITY_UNMET.
• Unknown top-level keys fail validation. The envelope is strict.
• Treat timeout, network errors, malformed responses, and serve:false as no-render.

These keys are rejected anywhere in the body: email, phone, tel, user_id, userid, userId, name, full_name, fullname, lat, lng, latitude, longitude, address, ip, conversation, conversation_history, messages, raw_message, app_id, placement, display_style, surface_id, capabilities.

Request examples

curl -sS -X POST "https://knobase.com/v1/offers/decide" \
  -H "Authorization: Bearer $KNOBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"시니어 반려견에게 줄 부드러운 사료를 찾고 있어요","locale":"ko","country":"KR","audience":{"age_band":"18_plus","contextual_offer_consent":true},"native_surface":{"clickable":true,"disclosure_capable":true}}'

Served-offer response

HTTP 200. disclosure, advertiser, and link are required commercial-integrity fields. title, description, image_url, and cta are optional presentation hints and do not instruct you to create a visual component. offer_id is the snapshot id used as offer_snapshot_id on events.

{
  "serve": true,
  "request_id": "req_01",
  "decision_id": "dec_01",
  "offer_id": "snp_01EXAMPLEOFFER",
  "expires_at": "2026-09-10T12:30:00.000Z",
  "disclosure": "광고",
  "advertiser": "Example Pet",
  "link": "https://knobase.com/r/tok_example",
  "title": "시니어 반려견을 위한 부드러운 식사 옵션",
  "description": "제품 정보와 원재료를 확인해보세요.",
  "cta": "제품 보기",
  "reason_codes": [
    "MATCHED"
  ]
}

No-fill response

HTTP 200 with serve:false is success. Keep the organic answer. Do not retry in a way that blocks the user.

{
  "serve": false,
  "request_id": "req_02",
  "decision_id": "dec_02",
  "reason_codes": [
    "NO_ELIGIBLE_OFFER"
  ],
  "retry_after_seconds": 0
}

Reason codes

Errors