Simbee
Log inGet started

Use Case Recipes

Each recipe shows how to configure and use Simbee for a specific application type. Recipes are short — they cover vocabulary design, signal types, scoring, and the key API flows, then link to the Concepts guide for deeper explanation.

Content recommendation

Vocabulary + Signals + Affinities + Feed

A platform where users consume content — articles, videos, courses, or music. Users interact with content, Simbee builds preference profiles, and the ranked feed surfaces personalized recommendations.

Vocabulary design

Tags represent content categories. Topics group related categories. Content is tagged when created; user signals against content inherit the content's tags.

Example: Video platform

  • Topics: Technology, Science, Arts, Lifestyle, Business
  • Tags: machine-learning, web-dev, physics, painting, cooking, startups

Signal types

Model the content consumption funnel with increasing strength:

# Low intent
curl -X POST $SIMBEE_URL/api/v1/config/signal_types \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "view", "label": "View", "strength_override": 0.1 }'

# Medium intent
curl -X POST $SIMBEE_URL/api/v1/config/signal_types \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "watch_50pct", "label": "Watch 50%", "strength_override": 0.4 }'

# High intent
curl -X POST $SIMBEE_URL/api/v1/config/signal_types \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "complete", "label": "Complete", "strength_override": 0.7 }'

# Strongest intent
curl -X POST $SIMBEE_URL/api/v1/config/signal_types \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "save", "label": "Save", "strength_override": 0.9 }'

Key API flow

  1. Register content via POST /api/v1/content with tags as metadata.
  2. Record user signals as they interact: view, watch_50pct, complete, save.
  3. Query GET /api/v1/users/{id}/feed/ranked to serve personalized recommendations.
  4. Monitor content performance via GET /api/v1/analytics/signals.

Scoring preset

Use affinity_matchfor "more of what you like" or diversityfor "explore new topics." Switch presets per-request to build different feed tabs (e.g. "For You" vs "Discover").

Community matching

Vocabulary + Signals + Affinities + Consent Layers + Scoring + Matches

An app that connects people with shared interests — hobby groups, study partners, professional networking. Users opt into matching and Simbee finds compatible connections.

Vocabulary design

Example: Hobby community

  • Topics: Outdoors, Creative, Tech, Music, Sports
  • Tags: hiking, climbing, pottery, watercolor, guitar, chess, running

Signal types

const signalTypes = [
  { key: "tag_interest",   label: "Tag Interest",   strength_override: 0.5 },
  { key: "group_join",     label: "Group Join",      strength_override: 0.7 },
  { key: "event_rsvp",     label: "Event RSVP",      strength_override: 0.8 },
  { key: "message_sent",   label: "Message Sent",    strength_override: 0.9 },
];

for (const st of signalTypes) {
  await configApi.createApiV1ConfigSignalType(st);
}

Consent layer setup

Create a consent layer so only users who opt in are matchable. Users who browse the community without opting in can still accumulate affinities but won't appear in match results.

# Create the consent layer
curl -X POST $SIMBEE_URL/api/v1/config/consent_layers \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "matching", "label": "Matching" }'

# User opts in
curl -X POST $SIMBEE_URL/api/v1/clients/cl_abc123/users/cu_xyz/consents \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "consent_layer_id": "matching", "granted": true }'

Key API flow

  1. Users select interests (recorded as tag_interest signals).
  2. Users opt into the "matching" consent layer.
  3. Query GET /api/v1/users/{id}/matches for compatible connections.
  4. Subscribe to match.computed webhooks to notify users of new matches.

Marketplace discovery

Scoring + Campaigns + Clustering + Feed + Analytics

A two-sided marketplace where buyers discover sellers. Simbee ranks sellers by relevance, promotes featured listings with campaigns, and segments buyers for targeted promotions.

Vocabulary design

Example: Services marketplace

  • Topics: Home Services, Professional, Creative, Technology
  • Tags: plumbing, electrician, photography, logo-design, web-dev, tutoring

Signal types

const signalTypes = [
  { key: "search",       label: "Search",        strength_override: 0.1 },
  { key: "view_profile", label: "View Profile",  strength_override: 0.3 },
  { key: "contact",      label: "Contact",       strength_override: 0.6 },
  { key: "purchase",     label: "Purchase",       strength_override: 1.0 },
  { key: "review",       label: "Review",         strength_override: 0.8 },
];

for (const st of signalTypes) {
  await configApi.createApiV1ConfigSignalType(st);
}

Promoted listings with campaigns

Sellers pay to promote their profiles. Create a campaign targeting buyers in relevant clusters. Simbee handles impression tracking, budget enforcement, and frequency capping.

// Create a promoted listing campaign
const { data: campaign } = await campaignsApi.createApiV1Campaign({
  name: "Featured Photographer - Spring 2026",
  budget: 500.0,
  target_criteria: {
    cluster_ids: ["cls_creative_seekers"],
  },
  max_impressions_per_user: 2,
  start_date: "2026-04-01",
  end_date: "2026-04-30",
});

// Add the seller's profile as a campaign item
await campaignsApi.createApiV1CampaignItem(campaign.data.id, {
  external_content_id: "seller_photography_pro",
});

// Activate
await campaignsApi.activateApiV1Campaign(campaign.data.id);

// Subscribe to budget alerts
await webhooksApi.createApiV1ClientWebhook("cl_abc123", {
  url: "https://marketplace.com/webhooks/simbee",
  event_types: ["campaign.budget_exhausted"],
  secret: "whsec_...",
});

Key API flow

  1. Create users for both buyers and sellers.
  2. Record buyer behavior as signals (search, view_profile, contact, purchase).
  3. Use GET /api/v1/users/{buyer_id}/feed/ranked for personalized seller discovery.
  4. Create campaigns for seller promotions with cluster-based targeting.
  5. Monitor performance via GET /api/v1/analytics/campaigns.

Scoring preset

Use engagement to surface sellers with the most buyer activity. Use affinity_matchto surface sellers whose category matches the buyer's history.

Event and group formation

Vocabulary + Signals + Clustering + Affinities

An app that automatically forms groups or cohorts — study groups, workshop teams, conference tracks, or fitness classes. Simbee clusters users by shared interests and affinity compatibility.

Vocabulary design

Example: Learning platform

  • Topics: Programming, Data Science, Design, Business
  • Tags: python, javascript, sql, figma, marketing, finance, react

Signal types

const signalTypes = [
  { key: "skill_declare",    label: "Skill Declared",     strength_override: 0.6 },
  { key: "course_enroll",    label: "Course Enrollment",  strength_override: 0.5 },
  { key: "lesson_complete",  label: "Lesson Complete",    strength_override: 0.7 },
  { key: "peer_collaborate", label: "Peer Collaboration", strength_override: 0.9 },
];

for (const st of signalTypes) {
  await configApi.createApiV1ConfigSignalType(st);
}

Using clusters as groups

After a clustering run, each cluster represents a natural grouping of users with similar learning paths. Use cluster membership to form study groups, assign workshop tracks, or pair mentors with learners.

// After clustering.completed webhook fires:
const { data: clusters } = await clusteringApi.listApiV1Clusters();

for (const cluster of clusters.data) {
  // Get members of this cluster
  const { data: members } = await clusteringApi.listApiV1ClusterMembers(
    cluster.id
  );

  // Form a study group from this cluster
  await createStudyGroup({
    name: `${cluster.label} Study Group`,
    members: members.data.map((m) => m.external_id),
    topic: cluster.label,
  });
}

Key API flow

  1. Users declare skills and enroll in courses (signals against tags).
  2. Wait for clustering to run (poll GET /api/v1/clustering_runs or listen for clustering.completed webhook).
  3. Read cluster membership via GET /api/v1/clusters/{id}/members.
  4. Use cluster labels and sizes to form appropriately-sized groups.
  5. Monitor for cluster.drift_detected to rebalance groups when interests shift.

Engagement analytics

Signals + Analytics + Webhooks

Use Simbee purely as a behavioral analytics pipeline — no personalization, no matching. Ingest user actions as signals, query aggregate analytics for dashboards, and subscribe to webhooks for real-time alerting.

Signal types as event taxonomy

Model your analytics event taxonomy as signal types. Strength values don't affect analytics aggregation, but they're useful if you later add personalization.

const signalTypes = [
  { key: "page_view",     label: "Page View",      strength_override: 0.1 },
  { key: "button_click",  label: "Button Click",   strength_override: 0.2 },
  { key: "form_submit",   label: "Form Submit",    strength_override: 0.5 },
  { key: "checkout_start", label: "Checkout Start", strength_override: 0.7 },
  { key: "purchase",      label: "Purchase",        strength_override: 1.0 },
];

for (const st of signalTypes) {
  await configApi.createApiV1ConfigSignalType(st);
}

Batch signal ingestion

For high-volume event ingestion, batch signals in groups of up to 1,000. This is more efficient than individual signal calls for analytics-heavy workloads.

curl -X POST $SIMBEE_URL/api/v1/signal_batches \
  -H "Authorization: Bearer $SIMBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signals": [
      {
        "external_id": "user_1",
        "signal_type_id": "page_view",
        "target_id": "/pricing",
        "target_type": "page"
      },
      {
        "external_id": "user_1",
        "signal_type_id": "button_click",
        "target_id": "cta-signup",
        "target_type": "element"
      },
      {
        "external_id": "user_2",
        "signal_type_id": "purchase",
        "target_id": "plan-pro",
        "target_type": "product"
      }
    ]
  }'

Dashboard queries

Build dashboards from the analytics endpoints. Each endpoint returns aggregated data scoped to your tenant.

const analytics = new AnalyticsApi(config);

// Overall activity
const { data: overview } = await analytics.getApiV1AnalyticsOverview();
console.log("Total users:", overview.data.totals.users);
console.log("Signals today:", overview.data.last_24h.signals_created);

// Signal breakdown by type
const { data: signals } = await analytics.getApiV1AnalyticsSignals();
console.log("Signal breakdown:", signals.data);

// Growth trends
const { data: growth } = await analytics.getApiV1AnalyticsGrowth();
console.log("Growth:", growth.data);

Key API flow

  1. Define your event taxonomy as signal types.
  2. Ingest events via individual signals or batches.
  3. Query GET /api/v1/analytics/* endpoints for dashboard data.
  4. Subscribe to clustering.completed to get automatic user segmentation as a bonus.
  5. Use GET /api/v1/analytics/vocabulary to see which tags/topics drive the most engagement.

Next steps

  • Concepts — Deep explanation of each primitive and how they compose.
  • Getting Started — Hands-on tutorial with all the API calls.
  • Webhooks — Event catalog, payload schemas, and signature verification.
  • API Reference — Full endpoint reference with request/response schemas.