API Documentation

Base URL: https://api.activationkit.com

All endpoints return JSON. Authentication is via the X-ND-Key header.

Quick Start

Get AI-powered user guidance running on your app in under 5 minutes. No npm install, no framework adapter, no tour authoring.

1

Create your account

Sign up for free — no credit card required. Your account starts on the Free plan with 25 AI conversations per month, forever.

2

Copy your API key

Go to Settings in the dashboard and copy your API key. It starts with nd_live_.

3

Add the script tag

Paste this snippet before the closing </body> tag on every page where you want guidance. Works with any framework — React, Vue, Angular, vanilla HTML.

<script>
  ActivationKit('init', {
    apiKey: 'YOUR_API_KEY',
    apiUrl: 'https://api.activationkit.com'
  });
</script>
<script src="https://api.activationkit.com/sdk/nd.js" defer></script>
4

Deploy and watch it work

Deploy your app. On the first page load, the SDK extracts your page structure and sends it to the API for AI enrichment. Within minutes, a help widget appears and the AI can answer questions about your product, highlight elements, and generate on-demand tours.

Check the Schema page in the dashboard to see what the AI discovered — routes, elements, sections, and tours.

5

Pass user context (optional)

For tier-aware guidance and per-user progress tracking, pass user identity in the init config. This enables the AI to detect gated features and suggest upgrades contextually.

<script>
  ActivationKit('init', {
    apiKey: 'YOUR_API_KEY',
    apiUrl: 'https://api.activationkit.com',
    user: {
      id: 'user_123',
      plan: 'pro'  // 'free', 'pro', or 'business'
    }
  });
</script>
<script src="https://api.activationkit.com/sdk/nd.js" defer></script>

How it works

  1. 1. The SDK extracts your page structure (elements, sections, navigation) on each page load.
  2. 2. It sends the extraction to the API, which builds a product schema via AI enrichment.
  3. 3. When a user needs help, the three-tier decision pipeline responds: Rules (<10ms) → Cache (<50ms) → LLM (500-2000ms).
  4. 4. ~70% of requests resolve without touching the LLM.

Authentication

Tenant API Key

All tenant endpoints require the `X-ND-Key` header with your API key. Find your key on the Settings page of the dashboard.

curl https://api.activationkit.com/v1/schema \
  -H "X-ND-Key: nd_live_your_key_here"

User Tracking (optional)

Pass `X-ND-User` header with a user ID to enable per-user progress tracking (completed tours, journey progress).

curl https://api.activationkit.com/v1/progress \
  -H "X-ND-Key: nd_live_your_key_here" \
  -H "X-ND-User: user_123"

SDK Configuration

Options passed to ActivationKit('init', options).

OptionTypeRequiredDescription
apiKeystringYesYour tenant API key from the dashboard Settings page.
apiUrlstringNoAPI base URL. Defaults to https://api.activationkit.com.
autoTriggerbooleanNoAuto-show guidance on page load. Default: true. Set to false for manual triggering.
user{ id, plan? }NoUser identity for progress tracking and tier-aware guidance.

Debugging

Enable debug mode to see detailed SDK decision logging in the browser console. Useful for troubleshooting element resolution, tour steps, and navigation issues.

Enable via Console (instant, session only)

Open DevTools and paste this in the Console tab:

window.__activationkit_debug = true

Enable via localStorage (persists across reloads)

For persistent debugging across page reloads:

localStorage.setItem('activationkit_debug', 'true');
// To disable: localStorage.removeItem('activationkit_debug');

Log Categories

Debug output is grouped by category so you can quickly find what you need:

CategoryWhat it logs
initSDK configuration, API URL, autoTrigger state
routerSPA route changes detected
contextContext API response — tours, actions, discovery state
actionsAuto-executed actions from chat or context
resolveElement resolution — method used, candidates tried
actionIndividual action execution details
sectionTab/section navigation attempts
extractorPage extraction — element count, sections, tabs
discoverySchema discovery — extractions sent, hash checks
sseChat stream connection, retries, parsed actions

Reporting Issues

Copy or screenshot the debug output and share it in #bug-reports on Discord for quick help, or email support@activationkit.com for sensitive issues.

Guidance

POST/v1/chat20/min

Get real-time AI guidance via Server-Sent Events. Send a user message and receive streamed response with actions.

Auth: X-ND-Key

Request

{
  "message": "How do I change the background color?",
  "page": "/dashboard",
  "userPlan": "pro",
  "activeSection": "Design",
  "sessionId": "session_abc",
  "chatHistory": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Response

// SSE stream:
data: {"type":"chunk","content":"To change the "}
data: {"type":"chunk","content":"background color..."}
data: {"type":"done","message":"To change the background color, go to the Design section.","actions":[{"type":"highlight_element","selector":"Background Color","message":"Click here to change it"}],"source":"llm"}
GET/v1/context

Get page-load guidance without a user message. Returns rules-based nudges, available tours, trial/usage info, and widget config.

Auth: X-ND-Key

Request

Query: ?page=/dashboard&userPlan=pro&journey=onboarding

Response

{
  "responseId": "resp_abc",
  "message": "Welcome back! Pick up where you left off.",
  "actions": [{ "type": "show_nudge", "message": "..." }],
  "source": "rule",
  "widgetEnabled": true,
  "discovery": false,
  "knownRoutes": ["/dashboard", "/settings"],
  "trial": { "active": false, "daysLeft": 0 },
  "usage": { "used": 12, "limit": 25, "limitReached": false }
}

Schema

GET/v1/schema

Retrieve the current tenant schema — routes, tours, journeys, and app metadata.

Auth: X-ND-Key

Response

{
  "appName": "My App",
  "appDescription": "A SaaS product",
  "routes": { "/dashboard": { "name": "Dashboard", "path": "/dashboard", ... } },
  "tours": { "onboarding": { "name": "Getting Started", "steps": [...] } },
  "journeys": {}
}
PUT/v1/schema

Replace the entire schema. Used for manual schema management.

Auth: X-ND-Key

Request

{ "appName": "...", "routes": {...}, "tours": {...}, "journeys": {...} }

Response

{ "ok": true, "routes": 5, "tours": 2 }
POST/v1/schema/discover10/min

Submit page extraction from the SDK. The API enriches it via AI and builds the schema. Fire-and-forget — returns immediately.

Auth: X-ND-Key

Request

{
  "route": { "path": "/dashboard" },
  "elements": [
    { "selector": "#save-btn", "role": "action", "name": "Save", ... }
  ]
}

Response

{ "received": true, "pagesDiscovered": 3, "schemaReady": true }
DELETE/v1/schema

Wipe the entire schema, cache, and extraction data. Triggers full re-discovery on next SDK page load.

Auth: X-ND-Key

Response

{ "ok": true, "schemaDeleted": true, "cacheCleared": true }

Progress Tracking

GET/v1/progress

Get progress for a specific user — completed steps, tours, and current journey.

Auth: X-ND-Key + X-ND-User

Response

{ "completedSteps": ["step_1"], "completedTours": ["onboarding"], "currentJourneyId": "setup" }
POST/v1/progress/step

Mark a tour step as completed.

Auth: X-ND-Key + X-ND-User

Request

{ "stepId": "step_1" }
POST/v1/progress/tour

Mark an entire tour as completed.

Auth: X-ND-Key + X-ND-User

Request

{ "tourId": "onboarding" }

Events & Health

POST/v1/events60/min

Ingest client-side events (page views, clicks, interactions). Fire-and-forget. Max 50 events per request.

Auth: X-ND-Key

Request

{ "events": [{ "type": "page_view", "url": "/dashboard", "page": "Dashboard" }], "sessionId": "session_abc" }

Response

{ "received": 3 }
GET/v1/selector-health

Get selector failure reports — elements the SDK couldn't resolve.

Auth: X-ND-Key

Response

{ "reports": [{ "selector": "#old-btn", "page": "/settings", "method": "failed", "count": 5 }], "count": 1 }
GET/v1/selector-health/summary

Quick summary of selector health — total reports, broken count, self-healed count.

Auth: X-ND-Key

Response

{ "totalReports": 12, "brokenSelectors": 2, "selfHealed": 10 }

Account & Billing

GET/v1/account/status

Get account status — current tier, trial info, conversation usage, and widget state.

Auth: X-ND-Key

Response

{
  "tier": "pro",
  "effectiveTier": "pro",
  "trial": { "active": false, "daysLeft": 0 },
  "usage": { "used": 150, "limit": 2500, "limitReached": false },
  "widgetEnabled": true
}
PATCH/v1/account/config

Update account configuration. Currently supports widget enable/disable toggle.

Auth: X-ND-Key

Request

{ "widgetEnabled": false }

Response

{ "widgetEnabled": false }
POST/v1/billing/checkout

Create a Stripe Checkout session. Redirect the user to the returned URL.

Auth: X-ND-Key

Request

{ "plan": "pro" }

Response

{ "url": "https://checkout.stripe.com/..." }
POST/v1/billing/portal

Create a Stripe Billing Portal session for subscription management.

Auth: X-ND-Key

Response

{ "url": "https://billing.stripe.com/..." }

Rate Limits

EndpointLimitWindow
POST /v1/chat20 requestsper minute
POST /v1/events60 requestsper minute
POST /v1/selector-health30 requestsper minute
POST /v1/schema/discover10 requestsper minute

Rate limits are per-tenant (keyed on API key + IP). Exceeding the limit returns 429 Too Many Requests.

Errors

All errors return JSON with an error field.

{ "error": "Invalid API key" }
StatusMeaning
400Bad request — missing or invalid parameters
401Unauthorized — invalid or missing API key
404Not found — resource doesn't exist
429Rate limited — too many requests
503Service unavailable — database or external service down

Pulse — Real-Time Alerts

Pulse delivers instant Slack alerts when your users experience errors, give negative feedback, submit testimonials, or approach usage limits. Your users' experience, delivered in real-time. Takes 2 minutes to set up.

1

Create a Slack Incoming Webhook

Go to api.slack.com/apps → Create New App → From scratch. Name it anything (e.g. "ActivationKit"). Then enable Incoming Webhooks, click Add New Webhook to Workspace, and select a channel.

Copy the webhook URL — it looks like https://hooks.slack.com/services/T.../B.../xxx

2

Paste it in Settings

Go to Settings in your ActivationKit dashboard. Scroll to Pulse — Real-Time Alerts, paste the webhook URL, and click Connect.

A test message is sent automatically to verify the connection.

3

Done — you'll receive these notifications

EventWhen it fires
Chat ErrorAI response failed for a user
Negative FeedbackUser gave a thumbs down
SDK Error Spike5+ client-side errors in one batch
Usage Limit80% of monthly conversations used
First ConversationA user has their first AI conversation
Schema GapAI referenced an element not in schema
Testimonial Ask SentMilestone email sent to a user
Testimonial ReceivedA user submitted feedback via milestone email

Notes

  • Notifications are throttled to 1 per event type per 5 minutes to prevent spam.
  • Slack's free plan works — no paid Slack required.
  • You can disconnect at any time from Settings.
  • Zero cost — Slack webhooks are free and add no load to your plan.

Need help?

Questions about integration? Join our Discord for quick help, or email for sensitive issues.