RecommendAI User Guide

RecommendAI — Plug-and-play AI recommendation engine for B2B SaaS products.

What Is RecommendAI?
Core Concepts
Getting Started — Admin
Admin Portal Reference
Getting Started — End Users
User Portal Reference
Integrating the API
Algorithms
Billing & Plans
SDK Quick-Start
FAQ

What Is RecommendAI?

RecommendAI is a multi-tenant recommendation engine SaaS. It allows developers and businesses to integrate personalised recommendations into their applications via a simple API — without building or maintaining ML infrastructure.

Key capabilities:

Collaborative filtering — Recommend based on what similar users liked
Content-based filtering — Recommend based on item attributes
Hybrid algorithm — Blend both for best accuracy
Deep learning — Neural embeddings for complex user/item relationships
Sub-50ms response times at production load

Architecture: Angular portals → .NET REST/GraphQL API → Rust recommendation core → PostgreSQL + Redis

Core Concepts

Concept	Description
Tenant	Your isolated account and dataset inside RecommendAI
Item	Any recommendable entity — product, article, song, video, etc.
User	An end user in your system who receives recommendations
Interaction	A signal from a user about an item (view, click, like, purchase)
Recommendation	A scored suggestion of an item for a specific user
Score	A 0–1 confidence value for how relevant an item is to a user
Algorithm	The ML model used to generate recommendations
API Key	A secret key used by your backend to call RecommendAI

Getting Started — Admin

1. Create Your Account

Navigate to the RecommendAI Admin Portal
Click Sign Up
Provide your email and create a password
Your tenant is provisioned automatically with a default API key

2. Ingest Your Items

Items are the entities you want to recommend (products, articles, videos, etc.).

Add items via the API:

bash

curl -X POST https://api.recommendai.io/api/items \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product-123",
    "metadata": {
      "title": "Wireless Headphones",
      "category": "Electronics",
      "price": 149.99,
      "tags": ["audio", "wireless", "premium"]
    }
  }'

Bulk-ingest items by sending an array or using the import endpoint.

3. Record Interactions

Send user behaviour signals as they happen in your application:

bash

curl -X POST https://api.recommendai.io/api/v1/interactions \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-abc",
    "itemId": "product-123",
    "interactionType": "view",
    "value": 1.0
  }'

4. Fetch Recommendations

Once you have items and interactions, fetch recommendations for any user:

bash

curl -X POST https://api.recommendai.io/api/v1/recommend \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-abc",
    "count": 10,
    "algorithm": "hybrid"
  }'

Admin Portal Reference

Dashboard

The admin dashboard shows tenant-wide platform statistics:

Metric	Description
Total Users	Users recorded in your tenant
Total Items	Catalogue items ingested
Total Recommendations	Recommendations generated to date
Total Interactions	Behaviour signals recorded
Active Models	ML models currently deployed for your tenant
Daily Active Users	Users who received recommendations in the last 24h
Avg Accuracy	Mean prediction accuracy across active models

User Management

Go to Users to manage the end users within your tenant.

Actions:

View all users with their status, role, and join date
Create users manually (or users self-register via your app)
Edit user attributes and role
Toggle user active/inactive status
Delete users

Roles:

Role	Description
`user`	Standard end user who receives recommendations
`admin`	Can access all admin portal sections

Recommendation Management

Go to Recommendations for a global view of all recommendations generated in your tenant.

Features:

View recommendations sorted by score, date, or user
Filter by algorithm type
Delete stale or unwanted recommendation records
Trigger a manual batch recommendation generation run

Batch generation:

Click Generate Recommendations
Select target user segment and algorithm
Set the number of recommendations per user
Click Run

Results appear in the list within seconds to minutes depending on dataset size.

Analytics

Go to Analytics for time-series dashboards on platform performance.

Available periods: Last 7 days, 30 days, 90 days

Charts:

Daily recommendations generated
Daily active users
Recommendation accuracy over time

Export: Download analytics data as CSV from the top-right menu.

Settings

Go to Settings to configure tenant-wide options:

Setting	Description
API Keys	View and rotate your tenant API keys
Algorithms	Enable/disable specific ML algorithms
Default Count	Default number of recommendations returned per request
Overage Cap	Maximum API overage spend per billing cycle
Webhook URL	Receive real-time event notifications

Admin Billing

Go to Billing to manage your RecommendAI subscription.

See Billing & Plans for full details.

Getting Started — End Users

End users access RecommendAI through:

Your application — recommendations surface via your UI, powered by the RecommendAI API
The RecommendAI User Portal — a self-service portal for users to view and manage their personalised recommendations

Navigate to the RecommendAI User Portal URL
Log in with your credentials (provisioned by the admin or via self-registration)
You land on the Home screen with a personalised summary

User Portal Reference

Home

The home screen shows:

A welcome message
Quick stats (items viewed, recommendations waiting)
A "Recommended for You" preview (top 3–5 items)

Recommendations

Go to Recommendations for your full personalised recommendation feed.

Features:

Scroll through all recommendations ranked by relevance score
See the reason each item was recommended (e.g., "Based on your interaction history")
Click an item to view its details
Mark recommendations as irrelevant ("Not for me") to improve future results

Profile

Go to Profile to manage your account:

Update display name and email
Change password
View your interaction history (items viewed, liked, purchased)
Request data export or account deletion (GDPR)

User Billing

If your tenant uses self-serve billing, go to Billing to:

View your current plan
Upgrade, downgrade, or cancel
View past invoices

Integrating the API

RecommendAI exposes a REST API (port 8080) and a GraphQL API (same port, /graphql). Your backend services call these with an API key — end users are never exposed to the key.

See the API Reference for complete endpoint documentation.

Quick integration example (Node.js)

const RECSYS_API_URL = 'https://api.recommendai.io';
const API_KEY = process.env.RECSYS_API_KEY;

// Record an interaction
async function trackView(userId, itemId) {
  await fetch(`${RECSYS_API_URL}/api/v1/interactions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ userId, itemId, interactionType: 'view', value: 1.0 }),
  });
}

// Get recommendations
async function getRecommendations(userId, count = 10) {
  const res = await fetch(`${RECSYS_API_URL}/api/v1/recommend`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ userId, count, algorithm: 'hybrid' }),
  });
  return res.json();
}

Algorithms

Algorithm	Best For	Cold Start
`collaborative`	Users with rich interaction history	Poor
`content-based`	New users; metadata-rich item catalogues	Good
`hybrid`	General purpose; balances both	Moderate
`deep-learning`	Large datasets; complex patterns	Moderate

Recommendation: Use hybrid for most production use cases. Fall back to content-based for users with fewer than 5 interactions.

Billing & Plans

Plans

Plan	Price/mo	API Requests	Items	Users
Starter	$49	10,000	1,000	500
Growth	$149	100,000	10,000	5,000
Scale	$499	1,000,000	100,000	50,000
Enterprise	Custom	Unlimited	Unlimited	Unlimited

Overage

When you exceed plan limits:

Overage is billed at $0.001 per additional API request
Set an Overage Cap in Settings to prevent unexpected charges
Once the cap is reached, requests return HTTP 402 Payment Required until the next billing cycle

Viewing Usage

Go to Billing → Usage to see:

API requests used vs. limit
Items ingested vs. limit
Users active vs. limit
Overage accrued this cycle

SDK Quick-Start

RecommendAI SDKs are available in the recommendai-sdks/ directory and on package registries. See recommendai-sdks/docs/ for language-specific guides.

Available SDKs: Go, .NET, Python, PHP, Ruby, TypeScript, Dart, Rust, Java, Kotlin, Swift

Core methods (all SDKs):

Method	Description
`recommend(userId, count, algorithm?)`	Get recommendations for a user
`similar(itemId, count)`	Find items similar to a given item
`recordInteraction(userId, itemId, type, value?)`	Record a user interaction
`ingestItem(id, metadata)`	Add or update an item in the catalogue
`deleteItem(id)`	Remove an item

TypeScript

bash

npm install @recommendai/js

typescript

import { RecommendAI } from '@recommendai/js';

const client = new RecommendAI({ apiKey: process.env.RECSYS_API_KEY! });

const recs = await client.recommend({ userId: 'user-123', count: 10 });
await client.recordInteraction({ userId: 'user-123', itemId: recs[0].itemId, type: 'click' });

Python

bash

pip install recommendai

python

from recommendai import RecommendAI

client = RecommendAI(api_key=os.environ["RECSYS_API_KEY"])
recs = client.recommend(user_id="user-123", count=10, algorithm="hybrid")

FAQ

How soon after ingesting items and interactions do recommendations appear? Recommendations are available in real time once items and interactions are ingested. Model training for deep-learning algorithms runs on a schedule (hourly by default).

What if a user has no interaction history? Use content-based or hybrid algorithm. The engine falls back to popularity-based recommendations until enough interactions accumulate.

Can I bring my own item metadata schema? Yes. The metadata field accepts any JSON object. Your schema is preserved and surfaced in recommendation responses.

Is multi-language item metadata supported? Yes. Metadata is stored and returned as-is. Filter by locale in your application layer or include locale as a metadata field.

How do I handle GDPR deletion requests? Call DELETE /api/users/{id} from the admin API. This deletes the user's interactions and recommendations. All associated data is purged within 24 hours.

Are there SDKs for mobile? Yes — Dart/Flutter, Kotlin (Android), and Swift (iOS) SDKs are available in recommendai-sdks/.

RecommendAI User Guide ​

Table of Contents ​

What Is RecommendAI? ​

Core Concepts ​

Getting Started — Admin ​

1. Create Your Account ​

2. Ingest Your Items ​

3. Record Interactions ​

4. Fetch Recommendations ​

Admin Portal Reference ​

Dashboard ​

User Management ​

Recommendation Management ​

Analytics ​

Settings ​

Admin Billing ​

Getting Started — End Users ​

User Portal Sign-In ​

User Portal Reference ​

Home ​

Recommendations ​

Profile ​

User Billing ​

Integrating the API ​

Quick integration example (Node.js) ​

Algorithms ​

Billing & Plans ​

Plans ​

Overage ​

Viewing Usage ​

SDK Quick-Start ​

TypeScript ​

Python ​

FAQ ​

RecommendAI User Guide

Table of Contents

What Is RecommendAI?

Core Concepts

Getting Started — Admin

1. Create Your Account

2. Ingest Your Items

3. Record Interactions

4. Fetch Recommendations

Admin Portal Reference

Dashboard

User Management

Recommendation Management

Analytics

Settings

Admin Billing

Getting Started — End Users

User Portal Sign-In

User Portal Reference

Home

Recommendations

Profile

User Billing

Integrating the API

Quick integration example (Node.js)

Algorithms

Billing & Plans

Plans

Overage

Viewing Usage

SDK Quick-Start

TypeScript

Python

FAQ