Public REST API

1. Mint an API key

Open the MBA admin on your platform and navigate to API keys. Click Create key. The plaintext mba_live_... is shown once, copy it now, we only store the SHA-256 hash and can't recover it later. Revoke and re-mint freely if a key leaks.

2. Make a request

Endpoint: GET /api/v1/recommendations

Auth: Bearer token in the Authorization header.

cURL

curl -H "Authorization: Bearer mba_live_..." \
  "https://app.marketbasketanalysis.com/api/v1/recommendations?product_id=8472918765&limit=3"

JavaScript / TypeScript

const response = await fetch(
  `https://app.marketbasketanalysis.com/api/v1/recommendations?` +
    new URLSearchParams({
      product_id: "8472918765",
      limit: "3",
    }),
  {
    headers: {
      Authorization: `Bearer ${process.env.MBA_API_KEY}`,
    },
  },
);

const data = await response.json();
console.log(data.recommendations);
// [
//   { productId: "...", sku: "SD-CARD-32", title: "32GB SD Card", confidence: 0.81 },
//   ...
// ]

Python

import os, requests

resp = requests.get(
    "https://app.marketbasketanalysis.com/api/v1/recommendations",
    headers={"Authorization": f"Bearer {os.environ['MBA_API_KEY']}"},
    params={"product_id": "8472918765", "limit": 3},
)
resp.raise_for_status()
print(resp.json()["recommendations"])

3. Query parameters

4. Response shape

{
  "recommendations": [
    {
      "productId": "gid://shopify/Product/8472918760",
      "sku": "SD-CARD-32",
      "title": "32GB SD Card",
      "confidence": 0.81
    }
  ],
  "model_version": "fpgrowth-2026-05-15",
  "shop_id": "12345"
}

When there are no qualifying co-purchase rules for the product, the array is empty. This is a 200, not a 404, absence of recommendations is a valid answer.

5. Errors

6. Sister endpoint: substitutions

The inverse of recommendations. Same auth, same query parameters, different question: not what should I buy with X, but what should I buy instead of X.

Endpoint: GET /api/v1/substitutions

curl -H "Authorization: Bearer mba_live_..." \
  "https://app.marketbasketanalysis.com/api/v1/substitutions?product_id=8472918765&limit=3"

Each item includes a score (0..1), a reason code (context_similar, category_match, vendor_match), and a signals block with the raw context-overlap, co-occurrence, and metadata flags that produced the score, so downstream agents can re-rank if their own criteria differ.

Built for autonomous-purchasing flows: when an agent's preferred SKU is out of stock, this endpoint gives a ranked fallback list without escalating to a human shopper.

7. Best practices

• Store the key as an env var. Never commit it.
• Cache responses for ~5 minutes when calling from your storefront. Recommendations don't change between mining runs.
• Pass either the numeric product id or the GID, whichever you have handy. The API normalizes both.
• Use the MCP server instead if you're wiring this into an AI agent, you get tool discovery and structured arguments for free.