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 URLhttps://us-central1-production-kainic.cloudfunctions.net
// 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.
// 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).
Uploads a product JSON file to the manual products connector. Supports two sync modes: full (replace entire catalog) and stock (inventory-only updates).
// 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.
🧪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_keyQuery parameter — Experiment API key used to authorize the request. REQUIRED
Request Headers
Content-Typeapplication/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.
// 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.
POST
Get Vector Search
Runs a free-text product search against the store's vector index, with optional vendor, collection, price, and metadata filtering. Results can optionally be reranked using the store's best-performing deployed personalized model.
ℹ️Out-of-stock products, and products with no stock value at all, are always excluded from results. Reranking only runs when rank_user_preferences: true and at least one of anon_uid / loggedin_uid is given — otherwise, and whenever reranking fails, products keep their raw similarity score.
Authentication
api_keyQuery parameter — validated against the api_key field of the vector_search document referenced by vector_search_id. REQUIRED
Request Headers
Content-Typeapplication/json
Request Body
Field
Type
Required
Description
user_query
string
REQUIRED
Free-text search query.
kainic_pid
string
REQUIRED
Kainic Project ID.
store_id
string
REQUIRED
Store ID. Combined with vector_search_id to build the Pinecone namespace ({store_id}_{vector_search_id}) and with kainic_pid to address the MySQL products database.
vector_search_id
string
REQUIRED
ID of the projects/{kainic_pid}/vector_search/{vector_search_id} document to search against.
limit
number
REQUIRED
Maximum number of products to return. Passed to Pinecone as top_k.
sid
string
OPTIONAL
Session ID — forwarded to the predictor service when reranking.
anon_uid
string
OPTIONAL
Anonymous user identifier — forwarded to the predictor service when reranking.
loggedin_uid
string
OPTIONAL
Logged-in user identifier (can be null) — forwarded to the predictor service when reranking.
rank_user_preferences
boolean
OPTIONAL
Default: false. If true, attempts to rerank results using the store's best-performing deployed personalized model (auto-discovered).
vendors
string[]
OPTIONAL
List of vendor names to filter results to.
collections
string[]
OPTIONAL
List of collection handles to filter results to.
min_price / max_price
number
OPTIONAL
Inclusive product price range.
metadata_filters
object
OPTIONAL
Dictionary of additional key/value-list filters, e.g. {"Color": ["Red", "Blue"]}. Each key must match a metadata field synced into Pinecone; values must be lists.
// Missing required fields (user_query, kainic_pid, store_id, vector_search_id, or limit)
{ "status": "fail", "message": "" } // 400
// Vector search not configured for this store
{ "status": "fail", "message": "vector search not configured for this store" } // 404
// Invalid or missing api_key
{ "status": "fail", "message": "AUTHENTICATION PROBLEM: Invalid ApiKey" } // 401
// Insufficient billing credit
{ "status": "fail", "message": "" } // 400
// Catalogue not yet synced (bq_to_pinecone has never completed a sync)
{ "status": "fail", "message": "" } // 400
// Missing Pinecone configuration, or a Pinecone/MySQL/Firestore failure
{ "status": "fail", "message": "" } // 500
Response Fields
Field
Type
Description
products
array
Ranked list of matching products. Empty when nothing matches.
score
float
When reranking ran: equal-weighted average of the normalized Pinecone similarity score and the model score (or the normalized Pinecone score alone if the product had no model score). Otherwise, the raw unnormalized Pinecone similarity score.
…other fields
mixed
Every other field comes directly from the store's MySQL product row for the matched product (or variant, depending on the store's search_target setting).