API Documentation

Integrate TenScore analytics into your SaaS application in minutes.

Quick Start

Get started with TenScore by creating a project in your dashboard and obtaining your API key.

Node.js SDK

The fastest way to integrate. Typed methods for all TenScore APIs.

npm install @tenscore/sdk

import { TenScore } from '@tenscore/sdk';

const ts = new TenScore({ apiKey: 'ts_live_YOUR_KEY' });

// Track an event
await ts.track({
  event: 'user_signed_up',
  distinct_id: 'user_123',
  properties: { signup_source: 'organic' },
});

// Track with idempotency (safe to retry)
await ts.track({
  event: 'subscription_created',
  distinct_id: 'user_123',
  idempotency_key: 'sub_abc_created',
  properties: {
    plan_id: 'pro',
    price_cents: 1900,
    billing_cycle: 'monthly',
    had_trial: false,
  },
});

// Get health score
const health = await ts.getHealth('project_id');
console.log(health.snapshot?.overallScore);

// Create a monitor
await ts.createMonitor({
  projectId: 'project_id',
  name: 'API Health',
  url: 'https://myapp.com/api/health',
});

REST API

Send events with any HTTP client. Works from any language or platform.

curl -X POST https://tenscore.cc/api/ingest \
  -H "Authorization: Bearer ts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user_signed_up",
    "distinct_id": "user_123",
    "timestamp": "2026-03-12T10:00:00Z",
    "tier": "free",
    "days_since_signup": 0,
    "session_number": 1,
    "signup_source": "organic"
  }'

Add idempotency_key to any event to safely retry without duplicates.

Next.js Integration

Track events from your Next.js API routes or server actions.

// lib/tenscore.ts
import { TenScore } from '@tenscore/sdk';

export const tenscore = new TenScore({
  apiKey: process.env.TENSCORE_API_KEY!,
});

// app/api/auth/signup/route.ts
import { tenscore } from '@/lib/tenscore';

export async function POST(req: Request) {
  const user = await createUser(req);

  await tenscore.track({
    event: 'user_signed_up',
    distinct_id: user.id,
    properties: { signup_source: 'organic' },
  });

  return Response.json({ user });
}

Stripe Webhook Integration

Track subscription events directly from Stripe webhooks for accurate revenue metrics.

// app/api/stripe/webhook/route.ts
import { tenscore } from '@/lib/tenscore';

// Inside your Stripe webhook handler:
case 'customer.subscription.created': {
  const sub = event.data.object;
  await tenscore.track({
    event: 'subscription_created',
    distinct_id: sub.metadata.user_id,
    idempotency_key: `stripe_${event.id}`,
    properties: {
      plan_id: sub.items.data[0].price.id,
      price_cents: sub.items.data[0].price.unit_amount,
      billing_cycle: sub.items.data[0].price.recurring?.interval === 'year' ? 'yearly' : 'monthly',
      had_trial: !!sub.trial_end,
    },
  });
  break;
}

case 'customer.subscription.deleted': {
  const sub = event.data.object;
  await tenscore.track({
    event: 'subscription_churned',
    distinct_id: sub.metadata.user_id,
    idempotency_key: `stripe_${event.id}`,
    properties: {
      plan_id: sub.items.data[0].price.id,
      churn_reason: sub.cancellation_details?.reason === 'payment_failed'
        ? 'payment_failed' : 'voluntary',
    },
  });
  break;
}

Segment Integration

Forward events from Segment to TenScore using a webhook destination.

1. In Segment, add a Webhook destination.

2. Set the URL to https://tenscore.cc/api/ingest

3. Add header: Authorization: Bearer ts_live_YOUR_KEY

4. Map your Segment events to TenScore canonical events:

Segment Event           → TenScore Event
────────────────────────────────────────
Signed Up               → user_signed_up
Account Activated       → user_activated
Feature Used            → feature_used
Session Started         → session_started
Trial Started           → trial_started
Subscription Created    → subscription_created
Subscription Renewed    → subscription_renewed
Subscription Cancelled  → subscription_churned
Plan Upgraded           → subscription_expanded
User Referred           → user_referred

Use Segment Functions to transform event payloads to match the TenScore schema. Each event requires distinct_id, timestamp, and event-specific properties.

Event Reference

TenScore tracks 10 canonical SaaS health metrics. Each maps to a health score dimension.

•user_signed_up — New user registrations (Acquisition)
•user_activated — Users reaching activation milestone (Activation)
•feature_used — Key feature usage (Engagement)
•session_started — Return visits (Retention)
•trial_started — Trial signups (Intent)
•subscription_created — New paid subscriptions (Conversion)
•subscription_renewed — Renewals (Revenue Retention)
•subscription_churned — Cancellations (Revenue Retention)
•subscription_expanded — Upgrades (Revenue Retention)
•user_referred — Referrals (Virality)

Need Help?

Questions about integration? Visit your dashboard to access your API keys and project settings. See what shipped recently on the changelog.