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.
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.
Copy your API key
Go to Settings in the dashboard and copy your API key. It starts with nd_live_.
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>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.
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. The SDK extracts your page structure (elements, sections, navigation) on each page load.
- 2. It sends the extraction to the API, which builds a product schema via AI enrichment.
- 3. When a user needs help, the three-tier decision pipeline responds: Rules (<10ms) → Cache (<50ms) → LLM (500-2000ms).
- 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).
| Option | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Yes | Your tenant API key from the dashboard Settings page. |
| apiUrl | string | No | API base URL. Defaults to https://api.activationkit.com. |
| autoTrigger | boolean | No | Auto-show guidance on page load. Default: true. Set to false for manual triggering. |
| user | { id, plan? } | No | User 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 = trueEnable 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:
| Category | What it logs |
|---|---|
| init | SDK configuration, API URL, autoTrigger state |
| router | SPA route changes detected |
| context | Context API response — tours, actions, discovery state |
| actions | Auto-executed actions from chat or context |
| resolve | Element resolution — method used, candidates tried |
| action | Individual action execution details |
| section | Tab/section navigation attempts |
| extractor | Page extraction — element count, sections, tabs |
| discovery | Schema discovery — extractions sent, hash checks |
| sse | Chat 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
/v1/chat20/minGet 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"}/v1/contextGet 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=onboardingResponse
{
"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
/v1/schemaRetrieve 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": {}
}/v1/schemaReplace the entire schema. Used for manual schema management.
Auth: X-ND-Key
Request
{ "appName": "...", "routes": {...}, "tours": {...}, "journeys": {...} }Response
{ "ok": true, "routes": 5, "tours": 2 }/v1/schema/discover10/minSubmit 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 }/v1/schemaWipe 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
/v1/progressGet 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" }/v1/progress/stepMark a tour step as completed.
Auth: X-ND-Key + X-ND-User
Request
{ "stepId": "step_1" }/v1/progress/tourMark an entire tour as completed.
Auth: X-ND-Key + X-ND-User
Request
{ "tourId": "onboarding" }Events & Health
/v1/events60/minIngest 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 }/v1/selector-healthGet 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 }/v1/selector-health/summaryQuick summary of selector health — total reports, broken count, self-healed count.
Auth: X-ND-Key
Response
{ "totalReports": 12, "brokenSelectors": 2, "selfHealed": 10 }Account & Billing
/v1/account/statusGet 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
}/v1/account/configUpdate account configuration. Currently supports widget enable/disable toggle.
Auth: X-ND-Key
Request
{ "widgetEnabled": false }Response
{ "widgetEnabled": false }/v1/billing/checkoutCreate a Stripe Checkout session. Redirect the user to the returned URL.
Auth: X-ND-Key
Request
{ "plan": "pro" }Response
{ "url": "https://checkout.stripe.com/..." }/v1/billing/portalCreate a Stripe Billing Portal session for subscription management.
Auth: X-ND-Key
Response
{ "url": "https://billing.stripe.com/..." }Rate Limits
| Endpoint | Limit | Window |
|---|---|---|
| POST /v1/chat | 20 requests | per minute |
| POST /v1/events | 60 requests | per minute |
| POST /v1/selector-health | 30 requests | per minute |
| POST /v1/schema/discover | 10 requests | per 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" }| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — invalid or missing API key |
| 404 | Not found — resource doesn't exist |
| 429 | Rate limited — too many requests |
| 503 | Service 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.
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
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.
Done — you'll receive these notifications
| Event | When it fires |
|---|---|
| Chat Error | AI response failed for a user |
| Negative Feedback | User gave a thumbs down |
| SDK Error Spike | 5+ client-side errors in one batch |
| Usage Limit | 80% of monthly conversations used |
| First Conversation | A user has their first AI conversation |
| Schema Gap | AI referenced an element not in schema |
| Testimonial Ask Sent | Milestone email sent to a user |
| Testimonial Received | A 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.