Kainic Platform

REST API Reference

Integrate Kainic's AI-powered personalization engine into your platform using our REST APIs. Collect events, request real-time recommendations, and sync your product catalog.

Base URL https://us-central1-production-kainic.cloudfunctions.net

Authentication

Scheme API Key

Location Query parameter — api_key

How to get Generate your API key from the Kainic Console

Available Endpoints

Endpoint	Method	Description
/collector/collect/custom/…	POST	Submit batches of user events from web, mobile, or POS platforms.
/predictor/get_model_prediction	POST	Get personalized product recommendations from a deployed model.
/upload_products_file	POST	Upload a JSON product catalog for full or stock-only sync.
/predictor/get_experiment_prediction	POST	Request a prediction from an active A/B testing experiment, with traffic distributed across models by session ID mapping.

Response Format

ℹ️ All endpoints return JSON. Successful responses carry "status": "success" and a "data" payload. Error responses carry "status": "fail" and a human-readable "message".

Rate Limiting & Retries

5xx errors Use exponential backoff. Honor Retry-After headers when present.

4xx errors Do not retry without correcting the request first.

POST

Custom Collector

Send tracked user events to Kainic's collector. Intended for client trackers to batch-submit events captured on web, mobile, or POS platforms.

POST https://us-central1-production-kainic.cloudfunctions.net/collector/collect/custom/{kainic_pid}/{kainic_tid}?api_key={api_key}

Authentication

api_key Query parameter — API key used to authorize the request. REQUIRED

Path Parameters

Parameter	Type	Required	Description
kainic_pid	string	REQUIRED	Kainic Project ID.
kainic_tid	string	REQUIRED	Kainic Tracker ID.

Request Headers

Content-Type application/json

Request Body

Array of Event objects (application/json).

Field	Type	Required	Description
platform	string	REQUIRED	Event platform. Allowed: `web`, `mobile`, `pos`.
anon_uid	string	REQUIRED	Anonymous user ID.
sid	string	REQUIRED	Session ID.
eid	string	REQUIRED	Event ID. For pageview events equals `pv_id`.
event_generated_unix_ts	integer	REQUIRED	Client-recorded event timestamp (Unix milliseconds).
category	string	REQUIRED	Event category (e.g., `ecom`).
action	string	REQUIRED	Event action (e.g., `view`, `purchase`).
loggedin_uid	string	OPTIONAL	Logged-in user ID.
pv_id	string	OPTIONAL	Page view ID; for pageview events equals `eid`.
label	string	OPTIONAL	Free-form label (e.g., item ID).
value	number	OPTIONAL	Free-form numeric value (e.g., quantity, rating).
data	array	OPTIONAL	Custom key/value event data. Each item: `{"key": string, "value": string}`.

Code Examples

bash

curl -X POST \
  "https://us-central1-production-kainic.cloudfunctions.net/collector/collect/custom/{kainic_pid}/{kainic_tid}?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "platform": "web",
      "loggedin_uid": "user420652863",
      "anon_uid": "c0c404ec-0407-4ff2-93e7-5a0ce615d6fa",
      "sid": "546f6af3-a517-4752-a98b-80c4g5860711",
      "pv_id": "3615d5b6-5d1f-4228-922a-1043bcfd7fb7",
      "eid": "1234f3s2-dd24-4432-vggt-91r4c586abRe",
      "event_generated_unix_ts": 1620486914000,
      "category": "ecom",
      "action": "view",
      "label": "i5726464",
      "value": 99.99,
      "data": [{ "key": "item_name", "value": "item5726464" }]
    }
  ]'

javascript

await fetch(
  "https://us-central1-production-kainic.cloudfunctions.net/collector/collect/custom/{kainic_pid}/{kainic_tid}?api_key=YOUR_KEY",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify([
      {
        platform: "web",
        anon_uid: "c0c404ec-0407-4ff2-93e7-5a0ce615d6fa",
        sid: "546f6af3-a517-4752-a98b-80c4g5860711",
        eid: "evt-abc",
        event_generated_unix_ts: Date.now(),
        category: "ecom",
        action: "view",
        label: "i5726464",
        value: 99.99,
        data: [{ key: "item_name", value: "item5726464" }]
      }
    ])
  }
);

Responses

200 OK 400 Bad Request

200 — Success

{
  "status": "success",
  "data": {}
}

400 — Errors

// Billing credit low
{ "status": "fail", "message": "Event Dismissed: Please top-up your project credit in order to collect events" }

// Tracker has no store
{ "status": "fail", "message": "Event Dismissed: Tracker does not have a store_id associated with it" }

// Domain not supported
{ "status": "fail", "message": "Event Dismissed: Domain Not Supported" }

// Missing required fields
{ "status": "fail", "message": "One or more required fields are missing!" }

// Field type mismatch
{ "status": "fail", "message": "Type of required field \"{field}\" is not {expected_type}" }

POST

Get Model Prediction

Requests a prediction from a Kainic deployed model, generating personalized product recommendations for a user in real time.

POST https://us-central1-production-kainic.cloudfunctions.net/predictor/get_model_prediction?api_key={api_key}

Authentication

api_key Query parameter — Model API key used to authorize the request. REQUIRED

Request Headers

Content-Type application/json

Request Body

Field	Type	Required	Description
kainic_pid	string	REQUIRED	Kainic Project ID.
kainic_mid	string	REQUIRED	Kainic deployed model ID.
platform	string	REQUIRED	Display platform. Allowed: `web`, `mobile`, `pos`.
anon_uid	string	REQUIRED	Anonymous user ID for personalization.
sid	string	REQUIRED	Session ID for session-level personalization.
type	string	REQUIRED*	Product category used as the ranking scope (e.g., `all_products`, `t-shirts`). *Required unless `items` is provided.
top_k	number	REQUIRED	Number of top-ranked items to return.
loggedin_uid	string	OPTIONAL	Logged-in user ID for whom recommendations are personalized.
items	string[]	OPTIONAL	Array of specific item IDs to rank. When provided, `type` is ignored.
return_full_items_data	boolean	OPTIONAL	Default: `false`. When `true`, includes full item metadata (image, handle, title, type, vendor, options, price).
exploration_rate	float	OPTIONAL	Default: `0.0`. Proportion of explored (popular) items blended with personalized results.
ignore_unsynced_products	boolean	OPTIONAL	Default: `true`. When `false`, unsynced items may appear in results.

Code Examples

json — request body (by type)

{
  "kainic_pid": "hHEpWLpDtJspf9qOfzqf",
  "kainic_mid": "VGTwHWDWXRHXnIxODIo1",
  "platform": "web",
  "loggedin_uid": "8669430710409",
  "anon_uid": "74709b4c-af9b-43b7-b40e-2e74db0900a1",
  "sid": "6be8d6a2-82ba-42be-b50d-fe27b56a1468",
  "type": "all_products",
  "top_k": 4,
  "return_full_items_data": true,
  "exploration_rate": 0
}

json — request body (by items)

{
  "kainic_pid": "hHEpWLpDtJspf9qOfzqf",
  "kainic_mid": "VGTwHWDWXRHXnIxODIo1",
  "platform": "web",
  "anon_uid": "74709b4c-af9b-43b7-b40e-2e74db0900a1",
  "sid": "6be8d6a2-82ba-42be-b50d-fe27b56a1468",
  "type": "all_products",
  "items": ["7980469715095", "8135192445079", "8125211803799", "6596543807639"],
  "top_k": 4,
  "return_full_items_data": false,
  "ignore_unsynced_products": true,
  "exploration_rate": 0
}

bash

curl -X POST \
  "https://us-central1-production-kainic.cloudfunctions.net/predictor/get_model_prediction?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kainic_pid": "uUWY1d1GYgCEUZ1jDKXz",
    "kainic_mid": "bxz4FlTK4lr5Qo9SrpMB",
    "platform": "web",
    "anon_uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "loggedin_uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "sid": "nbvfghjnbvfghj",
    "type": "all_products",
    "top_k": 4,
    "return_full_items_data": false,
    "ignore_unsynced_products": false,
    "exploration_rate": 0
  }'

Responses

200 OK 404 Not Found 500 Server Error

200 — Full items data

{
  "status": "success",
  "data": {
    "deployment_job_id": "18nvmqNhaV75EW5AIkbh",
    "uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "items": [
      {
        "item_id": "7980469715095",
        "parent_id": "7980469715095",
        "score": 1558.0,
        "title": "Leilani Cotton Kimono",
        "type": "Kimono",
        "vendor": "Clothing",
        "price": "2299.0",
        "compare_at_price": "None",
        "handle": "cotton-kimono-leilani?variant=43042082029719",
        "image": { "src": "https://cdn.shopify.com/…", "alt": "Leilani Cotton Kimono", "width": 1279, "height": 1600 },
        "options": [{ "key": "Size", "value": "S/M" }]
      }
    ]
  }
}

200 — Scores only (return_full_items_data: false)

{
  "status": "success",
  "data": {
    "deployment_job_id": "18nvmqNhaV75EW5AIkbh",
    "uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "items": [
      { "item_id": "7980469715095", "parent_id": "7980469715095", "score": 1558.0 },
      { "item_id": "8135192445079", "parent_id": "8135192445079", "score": 1137.0 }
    ]
  }
}

404 / 500 — Errors

// No type or items provided
{ "status": "fail", "message": "At least one of the following fields must be provided: [items, type]" }

// Model not deployed
{ "status": "fail", "message": "This model is not deployed!" }

// No endpoint for deployment job
{ "status": "fail", "message": "No endpoint is currently deployed for this model" }

// General failure
{ "status": "fail", "message": "Prediction request failed from project $KAINIC_PID: $ERROR" }

Response Item Fields

Field	Type	Description
item_id	string	Recommended item ID (parent or variant, based on model's `training_target`).
parent_id	string	Parent product ID.
score	float	Personalization relevance score.
title	string	Product title (when `return_full_items_data: true`).
type	string	Product category (when `return_full_items_data: true`).
price	string	Product price (when `return_full_items_data: true`).
image	object	Image object with `src`, `alt`, `width`, `height` (when `return_full_items_data: true`).
handle	string	URL-friendly product handle (when `return_full_items_data: true`).
options	array	Product variant options as `{"key","value"}` pairs.

POST

Upload Products File

Uploads a product JSON file to the manual products connector. Supports two sync modes: full (replace entire catalog) and stock (inventory-only updates).

POST https://us-central1-production-kainic.cloudfunctions.net/upload_products_file?api_key={api_key}

ℹ️ This endpoint accepts multipart/form-data. The upload is queued and processed asynchronously — the response returns when the file is accepted.

Authentication

api_key Query parameter — API key used to authorize the request. REQUIRED

Request Headers

Content-Type multipart/form-data

Form Fields

Field	Type	Required	Description
kainic_pid	string	REQUIRED	Kainic Project ID.
products_connector_id	string	REQUIRED	Kainic Manual product connector ID.
sync_type	enum	REQUIRED	Sync mode: `full` — replace/seed entire catalog. `stock` — update inventory only for existing products.
products	file (binary)	REQUIRED	JSON file containing the product catalog.

Code Examples

bash — full catalog sync

curl -X POST \
  "https://us-central1-production-kainic.cloudfunctions.net/upload_products_file?api_key=YOUR_KEY" \
  -F "kainic_pid=vUQYUAUpdGwAAVWafrKf" \
  -F "products_connector_id=0dR8mHaHmtG45aoOjo4k" \
  -F "sync_type=full" \
  -F "products=@/path/to/full_products.json;type=application/json"

bash — stock/inventory sync

curl -X POST \
  "https://us-central1-production-kainic.cloudfunctions.net/upload_products_file?api_key=YOUR_KEY" \
  -F "kainic_pid=vUQYUAUpdGwAAVWafrKf" \
  -F "products_connector_id=0dR8mHaHmtG45aoOjo4k" \
  -F "sync_type=stock" \
  -F "products=@/path/to/stock_products.json;type=application/json"

Responses

200 OK 400 Bad Request

200 — Success

{
  "status": "success",
  "data": {}
}

400 — Errors

// Insufficient credit
{ "status": "fail", "message": "Insufficient Credit !" }

// No file provided
{ "status": "fail", "message": "No file found" }

// File is empty
{ "status": "fail", "message": "File is empty: Store with id {store_id} does not exist" }

// Invalid JSON schema in file
{ "status": "fail", "message": "File schema is not valid" }

// Missing form fields
{ "status": "fail", "message": "One or more required fields are missing in the request body" }

POST

Get Experiment Prediction

Requests a prediction from an active Kainic A/B testing experiment. The system determines which deployed model to use based on session ID mapping, with traffic distributed across models according to user-defined percentage allocations to ensure balanced experiment coverage.

POST https://us-central1-production-kainic.cloudfunctions.net/predictor/get_experiment_prediction?api_key={api_key}

🧪 The model used for a given request is determined automatically by mapping the sid to an experiment group. If the mapped group has no model configured, the response returns an empty items array with kainic_mid: null.

Authentication

api_key Query parameter — Experiment API key used to authorize the request. REQUIRED

Request Headers

Content-Type application/json

Request Body

Field	Type	Required	Description
kainic_pid	string	REQUIRED	Kainic Project ID.
kainic_exp_id	string	REQUIRED	Kainic Experiment ID.
platform	string	REQUIRED	Display platform. Allowed: `web`, `mobile`, `pos`.
anon_uid	string	REQUIRED	Anonymous user ID for personalization.
sid	string	REQUIRED	Session ID — used to map the request to an experiment group.
type	string	REQUIRED*	Product category ranking scope (e.g., `all_products`). *Required unless `items` is provided.
top_k	number	REQUIRED	Number of top-ranked items to return.
loggedin_uid	string	OPTIONAL	Logged-in user ID for personalization.
items	string[]	OPTIONAL	Specific item IDs to rank. When provided, `type` is ignored.
return_full_items_data	boolean	OPTIONAL	Default: `false`. When `true`, includes full item metadata (image, handle, title, type, vendor, options, price).
exploration_rate	float	OPTIONAL	Default: `0.0`. Proportion of popular items blended into the top-K results.
ignore_unsynced_products	boolean	OPTIONAL	Default: `true`. When `false`, unsynced items may still appear — scored by fallback (average score, global average, or zero).

Code Examples

json — request body (by type)

{
  "kainic_pid": "hHEpWLpDtJspf9qOfzqf",
  "kainic_exp_id": "VGTwHWDWXRHXnIxODIo1",
  "platform": "web",
  "loggedin_uid": "8669430710409",
  "anon_uid": "74709b4c-af9b-43b7-b40e-2e74db0900a1",
  "sid": "6be8d6a2-82ba-42be-b50d-fe27b56a1468",
  "type": "all_products",
  "top_k": 4,
  "return_full_items_data": true,
  "exploration_rate": 0
}

json — request body (by items)

{
  "kainic_pid": "hHEpWLpDtJspf9qOfzqf",
  "kainic_exp_id": "VGTwHWDWXRHXnIxODIo1",
  "platform": "web",
  "anon_uid": "74709b4c-af9b-43b7-b40e-2e74db0900a1",
  "sid": "6be8d6a2-82ba-42be-b50d-fe27b56a1468",
  "type": "all_products",
  "items": ["7980469715095", "8135192445079", "8125211803799", "6596543807639"],
  "top_k": 4,
  "return_full_items_data": false,
  "ignore_unsynced_products": true,
  "exploration_rate": 0
}

bash

curl -X POST \
  "https://us-central1-production-kainic.cloudfunctions.net/predictor/get_experiment_prediction?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kainic_pid": "uUWY1d1GYgCEUZ1jDKXz",
    "kainic_exp_id": "bxz4FlTK4lr5Qo9SrpMB",
    "platform": "web",
    "anon_uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "loggedin_uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "sid": "nbvfghjnbvfghj",
    "type": "all_products",
    "top_k": 4,
    "return_full_items_data": false,
    "ignore_unsynced_products": false,
    "exploration_rate": 0
  }'

Responses

200 OK 404 Not Found 500 Server Error

200 — Full items data (session mapped to model)

{
  "status": "success",
  "data": {
    "deployment_job_id": "18nvmqNhaV75EW5AIkbh",
    "kainic_mid": "9fHFhkhgjjgu7snwna",
    "uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "items": [
      {
        "item_id": "7980469715095", "parent_id": "7980469715095", "score": 1558.0,
        "title": "Leilani Cotton Kimono", "type": "Kimono", "vendor": "Clothing",
        "price": "2299.0", "compare_at_price": "None",
        "handle": "cotton-kimono-leilani?variant=43042082029719",
        "image": { "src": "https://cdn.shopify.com/…", "alt": "Leilani Cotton Kimono", "width": 1279, "height": 1600 },
        "options": [{ "key": "Size", "value": "S/M" }]
      }
    ]
  }
}

200 — Scores only (return_full_items_data: false)

{
  "status": "success",
  "data": {
    "deployment_job_id": "18nvmqNhaV75EW5AIkbh",
    "kainic_mid": "9fHFhkhgjjgu7snwna",
    "uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "items": [
      { "item_id": "7980469715095", "parent_id": "7980469715095", "score": 1558.0 },
      { "item_id": "8135192445079", "parent_id": "8135192445079", "score": 1137.0 }
    ]
  }
}

200 — Session mapped to group with no model

{
  "status": "success",
  "data": {
    "kainic_mid": null,
    "deployment_job_id": "18nvmqNhaV75EW5AIkbh",
    "uid": "fe296f48-057b-4455-b102-e83c2458cfcb",
    "items": []
  }
}

404 / 500 — Errors

// Experiment not active
{ "status": "fail", "message": "The experiment is not active!" }

// No type or items provided
{ "status": "fail", "message": "At least one of the following fields must be provided: [items, type]" }

// Similarity-based model with no item ID
{ "status": "fail", "message": "No items requested to get similarities for!" }

// Model not deployed
{ "status": "fail", "message": "This model is not deployed!" }

// No endpoint for deployment job
{ "status": "fail", "message": "No endpoint is currently deployed for this model" }

// General failure
{ "status": "fail", "message": "Prediction request failed from project $KAINIC_PID: $ERROR" }

Response Fields

Field	Type	Description
deployment_job_id	string	Deployment job ID of the Kainic model used.
kainic_mid	string \| null	The model ID mapped to the experiment group for this session. `null` if the group has no model configured.
uid	string	Logged-in user ID if provided, otherwise `anon_uid`.
items	array	List of ranked item objects. Empty array when the mapped group has no model.