Documentation · v1

One path from install to evidence.

Choose a browser SDK, Node SDK, raw HTTP or MCP. They share the same canonical schema, permission model and evidence contract.

Start in five minutes OpenAPI 3.1

Create a scoped key

Server API keys remain secret. Browser project keys are origin-scoped, capped and revocable.

Choose one outcome

Start with signup, purchase, engagement or reliability. Semantic names make every later answer easier to trust.

Verify live data

Confirm environment, consent, masking, identity and outcome detection before inviting the team.

import { Apphelm } from "@sansavision/apphelm";

const apphelm = new Apphelm({
  apiKey: process.env.APPHELM_API_KEY
});

const products = await apphelm.listProducts();
const insight = await apphelm.getInsight("ins_activation_drop");

DEVELOPER SURFACES

Use the interface that fits the job.

Everything below is implemented in this repository and covered by contract or end-to-end tests.

REST API v1

Bearer auth, cursor pagination, idempotent drafts, correctness metadata and a canonical OpenAPI document.

Open the schema

npm SDK

@sansavision/apphelm for typed Node requests, consent-aware browser telemetry and a heartbeat CLI.

Install the package

Remote MCP

Streamable HTTP with ten tenant-scoped tools, Beam investigations, internal cost reads and draft-only action handling.

Connect an agent

Guided story

Learn the whole workflow through Northstar House’s fictional 47-minute recovery.

Read the story

Authentication

Better Auth magic links and email OTP, short sessions, D1 rate limiting and Cloudflare Email.

Open secure access

Status pages

Public product status URLs, compact iframe cards and tenant-scoped server heartbeats.

Publish status

NODE + BROWSER

Install the npm package.

The server client uses abortable requests and typed errors. Browser analytics begins disabled, and the replay capture chunk is dynamically loaded only after both analytics and replay consent are granted.

npm install @sansavision/apphelm

import { Apphelm } from "@sansavision/apphelm";

const apphelm = new Apphelm({
  apiKey: process.env.APPHELM_API_KEY
});

const products = await apphelm.listProducts();
const insight = await apphelm.getInsight("ins_activation_drop");

import { createBrowserSdk } from "@sansavision/apphelm/browser";

const analytics = createBrowserSdk({
  key: "ahl_pub_…",
  workspaceId: "org_…",
  productId: "prd_…",
  replay: { consentPolicyVersion: "consent_v1", sampleRate: 0.25 }
});

// Read this choice from your consent manager.
analytics.setConsent({ analytics: true, replay: true });
analytics.page();
analytics.track({ name: "signup_completed" });
if (analytics.isEnabled("new-checkout")) renderNewCheckout();
analytics.captureException(error);

AGENT SURFACE

Connect the remote MCP server.

Use an Apphelm API key as a Bearer token. Tools can read products, metrics, insights, sessions and incidents, call Beam, or prepare a draft. No MCP tool performs an external mutation.

Human confirmation stays mandatory. Draft tools never create issues, deploy code or change production.

{
  "mcpServers": {
    "apphelm": {
      "url": "https://apphelm.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${APPHELM_API_KEY}"
      }
    }
  }
}

PUBLIC STATUS

Paste a URL and publish.

Create a page in Status pages and paste any public HTTPS page or health endpoint. Apphelm checks it immediately and every five minutes after that—no monitoring code required. The signed heartbeat shown here remains available for private systems and richer health signals.

Public by design. Display names and status messages are customer-visible. Monitor targets, workspace IDs and telemetry remain private.

curl -X POST https://apphelm.dev/api/v1/status/heartbeat \
  -H "Authorization: Bearer $APPHELM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId":"prd_…","status":"operational","responseTimeMs":214}'

<iframe
  src="https://apphelm.dev/status/your-page/embed"
  title="Service status"
  loading="lazy"
  sandbox="allow-popups"
  style="width:100%;height:148px;border:0;border-radius:16px">
</iframe>

MOVING FROM POSTHOG

Import a PostHog export.

In the app, open Settings, then Import from PostHog. Choose a product and upload one export file: PostHog's batch export of events as JSON Lines, gzipped or not, up to 50 MB and 100,000 rows. You get a full preview first: events by name, and every row that would be left out with its reason. Nothing is written until you confirm, and an import can be undone for 30 days.

Events keep their own dates, within what your plan keeps. $pageview is stored as page_viewed. The import brings in events only: people are not imported, so send them from your own server with identify. IP addresses, user agents, page content and PostHog's own properties are never imported; nor are exceptions, recordings, cohorts, dashboards or flag definitions.

Imported events do not use your monthly event allowance. They are counted separately, up to 250,000 a day, and never trigger an alert, a webhook or an email.

{"uuid":"018f3b5a-…","event":"$pageview","distinct_id":"user-1",
 "timestamp":"2026-09-01T10:00:00Z",
 "properties":{"$current_url":"https://app.example.com/pricing","plan":"builder"}}
{"uuid":"018f3b5b-…","event":"signup_completed","distinct_id":"user-1",
 "timestamp":"2026-09-01T10:05:00Z",
 "properties":{"plan":"builder","$set":{"plan":"builder"}}}

Consent first

Analytics and replay are disabled until an explicit choice. Replay loads separately, stores no text or field values, and blocks sensitive routes by default.

Evidence first

Beam returns classification, confidence, evidence, counter-evidence, impact, queries and data-quality warnings.

Least privilege

Server secrets stay in Wrangler secrets. Browser keys are not accepted as server credentials. MCP uses the same scoped API boundary.