REST API Documentation
Integrate Mqora into your existing POS system or e-commerce platform.
Base URL
http://localhost:5000/api
All endpoints return JSON. Most endpoints work without authentication (using the
default tenant). Premium endpoints require an API key in the
X-Mqora-Key header.
Authentication
Register to get a free API key, then send it with every request:
POST /api/register
{"name": "My Store", "shop_domain": "store.myshopify.com"}
Response:
{
"api_key": "sk_abc123...",
"tenant_id": "t_xyz789...",
"status": "ok"
}
# Then use it:
curl -H "X-Mqora-Key: sk_abc123..." http://localhost:5000/api/arrangement
Endpoints
GET
/api/health
Health check — engine status, product count, receipt count.
GET
/api/stats
Dashboard summary: total receipts, products, categories, top products, avg items per receipt.
GET
/api/products
Full product catalog with purchase counts.
GET
/api/related/<product_id>
KNN related products for a specific product. Optional
?k=3 to limit neighbours.
GET
/api/relationships
All product relationships in one call. Useful for bulk-loading into a website or POS cache.
GET
/api/arrangement
Recommended shelf/section groupings (zones) based on KNN affinity.
GET
/api/network
Network graph data (nodes + edges) for visual rendering on your own site.
GET
/api/cooccurrence
Top co-occurring product pairs. Optional
?min_count=3&limit=30.
GET
/api/category-affinity
Cross-category co-occurrence counts. Shows which categories to place near each other.
GET
/api/association-rules
Market basket association rules (support, confidence, lift, conviction). Optional
?min_support=0.01&min_confidence=0.2&min_lift=1.0&limit=50.
GET
/api/association-rules/<product_id>
Association rules for a specific product as antecedent or consequent. Optional
?direction=consequent.
GET
/api/analytics
Sales analytics — top products by revenue and units, category performance
(revenue, units, share %), product velocity (fast/slow movers), basket size distribution,
and auto-generated actionable insights.
GET
/api/analytics/top-products
Top selling products by revenue and by units sold. Optional
?limit=20.
GET
/api/analytics/categories
Category performance breakdown: revenue, units sold, product count, revenue share %.
GET
/api/analytics/insights
Auto-generated actionable insights: top revenue category, cross-sell opportunities, slow movers, fast movers, revenue concentration risk.
GET
/api/premium/insights
Premium (requires API key). Cross-merchant insights: industry benchmarks,
trending product combinations and category affinity across the Mqora network.
Send your key in the
X-Mqora-Key header.
POST
/api/premium/data-sharing
Opt in or out of cross-merchant data sharing (premium feature).
Body:
{"enabled": true}. Requires X-Mqora-Key header.
Only anonymized statistical patterns are shared — never store identity or individual receipts.
POST
/api/basket/recommend
Given a basket of product IDs, recommend what the customer would likely add next. Body:
{"basket": ["P001", "P009"], "top_n": 10}.
POST
/api/register
Register a new tenant and receive an API key. Body:
{"name": "My Store", "shop_domain": "store.myshopify.com"}.
GET
/api/export/arrangement/csv
Download arrangement plan as CSV file.
GET
/api/export/relationships/csv
Download all product relationships as CSV file.
GET
/api/export/rules/csv
Download all association rules as CSV file.
POST
/api/receipts
Upload receipts as JSON array in request body. Engine re-trains automatically.
POST
/api/receipts/file
Upload CSV or JSON file via multipart form-data. Engine re-trains automatically.
POST
/api/retrain
Re-train KNN with a different K value. Send
{"k": 7} in JSON body.Integration Examples
1. POS: Get related products when an item is scanned
GET /api/related/P001
Response:
{
"product_id": "P001",
"product_name": "White Bread Loaf",
"category": "Bakery",
"related_products": [
{"product_id": "P012", "product_name": "Butter (1 lb)", "category": "Dairy", "score": 0.87, "co_occurrence": 142},
{"product_id": "P017", "product_name": "Eggs (dozen)", "category": "Dairy", "score": 0.82, "co_occurrence": 128},
...
]
}
2. Website: Load arrangement zones for category page
GET /api/arrangement
Response:
[
{
"group_id": 1,
"label": "Bakery + 2 Zone",
"affinity_score": 0.78,
"products": [
{"product_id": "P001", "product_name": "White Bread Loaf", "category": "Bakery"},
{"product_id": "P012", "product_name": "Butter (1 lb)", "category": "Dairy"},
...
]
},
...
]
3. cURL: Upload receipts from a script
curl -X POST http://localhost:5000/api/receipts \
-H "Content-Type: application/json" \
-d '[
{"receipt_id":"R001","product_id":"P001","product_name":"Bread","quantity":2,"unit_price":2.49,"category":"Bakery"},
{"receipt_id":"R001","product_id":"P009","product_name":"Milk","quantity":1,"unit_price":3.29,"category":"Dairy"}
]'
4. Python: Fetch related products in your POS app
import requests
resp = requests.get("http://localhost:5000/api/related/P001", params={"k": 3})
data = resp.json()
for p in data["related_products"]:
print(f" {p['product_name']} (score={p['score']})")
5. Sales analytics: find where to focus
GET /api/analytics/insights
Response:
{
"total_revenue": 51778.55,
"total_units_sold": 12802,
"avg_basket_size": 7.52,
"insights": [
{
"type": "focus",
"title": "Pantry is your top revenue category",
"detail": "Generates $10051 (19.4%) of total revenue. Ensure this
category has premium shelf placement...",
"priority": "high"
},
{
"type": "cross_sell",
"title": "Customers who buy Cream Cheese also buy Tea Bags (box)",
"detail": "Lift: 15.5x — Confidence: 75%. Place these near each
other or bundle them to boost sales.",
"priority": "high"
},
...
]
}
6. Premium: cross-merchant insights (requires API key)
curl -H "X-Mqora-Key: sk_your_api_key" \
http://localhost:5000/api/premium/insights
Response includes:
{
"total_revenue": 51778.55,
"tenant_name": "My Store",
"data_sharing_enabled": true,
"cross_merchant": {
"trending_combinations": [...],
"trending_categories": [...],
"network_stats": {
"merchants_contributing": 12,
"unique_products": 340,
"receipts_analyzed": 15400
}
}
}
Quick Test