API Reference

Register or update a device. Returns the device record with assigned segment.

Request Body

Response (200)

{
  "success": true,
  "device": {
    "id": 42,
    "android_id": "abc123",
    "user_segment": "active",
    "created_at": "2026-03-01 12:00:00"
  }
}

Update a device's FCM push notification token.

Submit a batch of events (up to 50 per request). Events are processed transactionally.

{
  "events": [
    {
      "android_id": "abc123",
      "event_type": "ad_watched",
      "event_data": {"ad_network": "admob", "reward": 10},
      "created_at": "2026-03-20 14:30:00"
    },
    {
      "android_id": "abc123",
      "event_type": "page_view",
      "event_data": {"page": "settings"}
    }
  ]
}

Auto-register app + device on first launch. Uses X-API-Key (org key) instead of X-SDK-Key. Returns sdk_key for all future SDK calls. If app already exists, returns existing key.

Auth: X-API-Key: {org_api_key}

Response:

{
  "success": true,
  "sdk_key": "sk_b8695b97f896766c",
  "app_id": 9,
  "device_id": 5010881,
  "app_action": "existing",
  "device_action": "registered"
}

Full user profile with segment, ad strategy (33 fields), country, ad watches, purchase history. Replaces v3 UserSegmentationRepo.

Auth: X-SDK-Key

{
  "success": true,
  "profile": {
    "device_id": 203,
    "segment": "ACTIVE_USER",
    "country": "IN",
    "total_ad_watches": 47,
    "days_since_first_install": 102,
    "ad_strategy": {
      "ads_enabled": true,
      "interstitial_enabled": true,
      "ad_cooldown_sec": 90,
      "interstitial_cap": 3,
      "interstitial_daily_cap": 8,
      "rewarded_cap": 15,
      "app_open_cooldown_sec": 2400,
      "app_open_daily_cap": 3,
      "pre_show_delay_ms": 1500,
      "config_version": 2
    }
  }
}

Update user action and recalculate segment. Actions: ad_watched, purchase_made, update_country, app_update, session_start.

Auth: X-SDK-Key

// Request
{ "android_id": "9fd960b07a8c4327", "action": "ad_watched" }

// Response
{ "segment": "POWER_USER", "ad_strategy": { ... } }

Track ad revenue events with network, type, geo tier, and estimated revenue.

Auth: X-SDK-Key

{
  "android_id": "9fd960b07a8c4327",
  "ad_type": "rewarded",
  "ad_network": "admob",
  "revenue": 0.0035,
  "ecpm": 3.50,
  "geo_tier": "tier3",
  "country": "IN"
}

List all tracked Play Store apps for the organization. Auth: JWT.

Scrape app metadata from Google Play Store. Body: { "package_name": "com.example.app" }. Auth: JWT.

Compare multiple apps side by side. Body: { "packages": ["com.app1", "com.app2"] }. Auth: JWT.

List cross-promotion campaigns. CRUD: GET (list), POST (create), PUT /:id (update), DELETE /:id. Auth: JWT.

Campaign performance: impressions, clicks, installs, CTR. Auth: JWT.

AI-powered campaign recommendations based on app performance and user segments. Auth: JWT.

CRUD for automation rules. Triggers: rating_drop, download_spike, negative_review_spike, new_version_detected, competitor_update. Actions: telegram, webhook, email. Auth: JWT.

Automation execution history. Auth: JWT.

Inter-agent message queue. Used by OpenClaw (.209) and Claude Channels (.211) to communicate with the platform. Auth: JWT.

Multi-turn AI chat powered by Claude. Supports conversation history. Body: { "message": "How are my apps doing?", "conversation_id": 1 }. Auth: JWT.

Correlate Play Store metrics with internal analytics data. Auth: JWT.

App Store Optimization recommendations based on competitor analysis. Auth: JWT.

Generate AI reports. Types: daily_summary, weekly, competitor, revenue, review. Auth: JWT.

Analyze review sentiment using Claude Haiku. Auth: JWT.

CodeClaw agent status: open issues, fixed issues, job history. Auth: JWT.

Run PHP lint on all project files. Returns error count and details. Auth: JWT.

Run security scan: SQL injection, XSS, hardcoded credentials, insecure headers. Auth: JWT.

Full system status: git branch, DB latency, table counts, agent status, API stats, disk/memory usage. Auth: JWT or X-Admin-Token.

Trigger deployment to dev or production. Auth: X-Admin-Token.

List published blog posts with title, slug, excerpt, date. Auth: JWT.

AI-generate a blog article draft. Body: { "topic": "...", "keywords": [...] }. Auth: JWT.

List all webhooks. Returns name, URL, subscribed events, active status. Auth: JWT.

Create webhook. Body: { "url": "https://...", "events": ["device.registered", "event.batch"], "name": "My Hook" }. Returns webhook secret for HMAC verification. Auth: JWT.

Send test payload to webhook URL. Returns status code and response time. Auth: JWT.

Get/update theme settings (primary color, mode, sidebar style). GET to read, PUT to update. Auth: JWT.

Activity log with user actions, timestamps, IP addresses. Filterable by action type. Auth: JWT.

Create a new organization and owner user account. Returns a JWT token.

// Response
{
  "token": "eyJhbGciOiJIUzI1NiI...",
  "user": { "id": 5, "org_id": 3, "role": "owner" }
}

Authenticate with email and password. Returns a JWT token valid for 24 hours.

// Request
{ "email": "user@example.com", "password": "your-password" }

// Response
{
  "token": "eyJhbGciOiJIUzI1NiI...",
  "user": { "id": 1, "org_id": 1, "role": "owner" }
}

Exchange a valid (non-expired) JWT for a fresh token.

List all apps belonging to the authenticated user's organization.

{
  "apps": [
    { "id": 1, "name": "My App", "package_name": "com.example.myapp", "sdk_key": "sk_..." }
  ]
}

Key metrics for an app: total devices, active users (30d), new users (7d), events today, ad watches, purchases.

Returns device counts grouped by user segment (e.g., power_user, active, casual, dormant, churned).

Paginated device list with filtering.

Daily time-series data for the specified period. Returns active_devices, new_devices, total_events per day.

Device counts grouped by country code, sorted descending.

Ask questions in plain English. Claude AI translates your question to SQL, executes it safely, and returns results with a narrative explanation.

// Request
{ "query": "How many users from India watched more than 50 ads this month?" }

// Response
{
  "answer": "There are 142 users from India who watched more than 50 ads...",
  "sql": "SELECT COUNT(*) FROM devices WHERE ...",
  "data": [{"count": 142}]
}

Returns cached AI-generated insights (daily summaries, anomaly alerts, weekly reports).

Identifies devices at risk of churning with AI-generated risk scores and recommended actions.

Returns the current subscription plan, status, and period end date for the authenticated organization.

{
  "plan": "pro",
  "status": "active",
  "current_period_end": "2026-04-20T00:00:00Z",
  "limits": { "apps": 10, "devices": 100000, "events_per_month": 10000000 }
}

Creates a Stripe Checkout session for upgrading to a paid plan.

// Request
{ "plan": "pro" }  // "starter", "pro", or "enterprise"

// Response
{ "checkout_url": "https://checkout.stripe.com/c/pay/cs_..." }

Creates a Stripe Customer Portal session for managing payment methods, invoices, and subscription changes.

{ "portal_url": "https://billing.stripe.com/p/session/..." }

Cancels the current subscription at the end of the billing period. Access continues until period end.

Send a push notification to a device, segment, or all users.

// Send to segment
{
  "app_id": 1,
  "target": "segment",
  "segment": "dormant",
  "title": "We miss you!",
  "body": "Come back and check out new features.",
  "data": {"screen": "home"}
}

// Send to single device
{ "app_id": 1, "target": "device", "device_id": 42, "title": "...", "body": "..." }

// Broadcast to all
{ "app_id": 1, "target": "all", "title": "...", "body": "..." }

Returns the last 50 notifications sent or scheduled for the app, newest first.

{
  "notifications": [
    {
      "id": 12,
      "title": "Flash Sale!",
      "body": "50% off premium today only.",
      "target": "all",
      "segment": null,
      "sent": 3219,
      "failed": 12,
      "status": "delivered",
      "sent_at": "2026-03-21 10:30:00",
      "created_at": "2026-03-21 10:30:00"
    }
  ]
}

Returns all A/B experiments for the app with variant assignments count.

Create a new A/B test experiment.

{
  "app_id": 1,
  "name": "CTA Button Color",
  "description": "Test green vs orange CTA buttons",
  "variants": [
    {"key": "control", "name": "Green", "weight": 50},
    {"key": "variant_a", "name": "Orange", "weight": 50}
  ],
  "target_metric": "purchase"
}

Change experiment status: draft → running → paused / completed.

{ "app_id": 1, "status": "running" }

Returns all feature flags for the app with their current status and rollout percentage.

Create a new feature flag. Supports boolean and multivariate types.

// Boolean flag
{
  "app_id": 1,
  "flag_key": "new_onboarding",
  "name": "New Onboarding Flow",
  "flag_type": "boolean",
  "is_enabled": true,
  "rollout_pct": 25
}

// Multivariate flag
{
  "app_id": 1,
  "flag_key": "cta_color",
  "name": "CTA Button Color",
  "flag_type": "multivariate",
  "is_enabled": true,
  "rollout_pct": 100,
  "variants": [
    {"key": "green", "value": "#22C55E", "weight": 50},
    {"key": "orange", "value": "#F59E0B", "weight": 50}
  ]
}

Update a flag's enabled state, rollout percentage, or variants. All fields are optional.

{ "app_id": 1, "is_enabled": true, "rollout_pct": 50 }

Returns evaluated feature flags for a specific device. Uses CRC32-based deterministic assignment so the same device always gets the same variant.

{
  "flags": {
    "new_onboarding": { "enabled": true, "type": "boolean" },
    "cta_color": {
      "enabled": true,
      "type": "multivariate",
      "variant": "green",
      "value": "#22C55E"
    }
  }
}

Streams all devices as a CSV file. Rate limited to 5 requests per hour.

Streams the last 30 days of events as a CSV file. Rate limited to 5 requests per hour.

List all webhooks for an app. Returns name, URL, subscribed events, active status, and failure count.

Create a new webhook (max 10 per app). Returns a signing secret — store it securely.

{
  "app_id": 1,
  "name": "Analytics Hook",
  "url": "https://example.com/webhook",
  "events": ["session_start", "purchase", "*"]
}

Supported events: session_start, session_end, purchase, ad_watched, page_view, feature_used, notification_clicked, * (all).

Update webhook name, URL, events, or active status. Send only fields to update.

Permanently delete a webhook and all its delivery history.

Send a test payload to verify your endpoint. Returns the HTTP response code and body.

Get the last 25 delivery attempts for a webhook. Includes response code, duration, and status.

List all custom segments for an app, including rules, cached device count, and last calculation time.

Create a custom segment with rules (max 20 per app).

{
  "app_id": 1,
  "name": "Power Users India",
  "description": "High-engagement users from India",
  "logic": "AND",
  "color": "#22c55e",
  "rules": [
    { "field": "country", "operator": "eq", "value": "IN" },
    { "field": "session_count_30d", "operator": "gte", "value": "50" }
  ]
}

Operators: eq, neq, gt, gte, lt, lte, contains

Update segment name, rules, logic, color, or active status.

Recalculate segment membership on demand. Returns the updated device count.

// Response
{ "device_count": 1204, "segment_id": 5 }

List all alert rules and recent alert history for an app.

{
  "app_id": 1,
  "name": "DAU Drop Alert",
  "metric": "dau",
  "condition": "drops_by",
  "threshold": 20,
  "compare_window": "week",
  "channel": "email"
}

Metrics: dau, new_users, events, ad_watches, purchases, crash_rate, churn_rate

Conditions: drops_by, increases_by, below, above

Channels: email, webhook, dashboard

Delete an alert rule.

Analyze conversion funnel for a sequence of events. Pass ordered event types to calculate drop-off at each step.

{
  "app_id": 1,
  "steps": ["session_start", "page_view", "ad_watched", "purchase"],
  "from": "2026-03-01",
  "to": "2026-03-21"
}

Get cohort retention data. Returns weekly cohorts with day-1, day-7, day-14, day-30 retention rates.

Analyze most common user event sequences. Returns top N paths with their frequency and conversion data.

{ "app_id": 1, "start_event": "session_start", "depth": 5, "limit": 20 }

List all custom dashboards for an app. Each dashboard contains an array of widget configurations.

{
  "app_id": 1,
  "name": "Growth Overview",
  "widgets": [
    { "type": "kpi", "metric": "active_devices", "label": "DAU" },
    { "type": "line_chart", "metric": "new_devices", "label": "New Users" }
  ]
}

Widget types: kpi, line_chart, bar_chart, pie_chart

Update dashboard name or widgets array.

List all team members in the organization with their role (owner, admin, viewer).

{ "email": "newmember@example.com", "role": "admin" }

Roles: owner (full access), admin (manage apps, view billing), viewer (read-only).

Update a team member's role. Requires admin or owner access.

Remove a team member from the organization. Cannot remove the owner.

Health check endpoint (no auth required). Returns status of all services.

// Response
{
  "status": "ok",
  "database": { "status": "ok", "latency_ms": 2 },
  "redis": { "status": "ok" },
  "storage": { "writable": true, "free_gb": 45.2 },
  "queue": { "status": "ok", "pending_jobs": 3 },
  "php_version": "8.2.15",
  "uptime_seconds": 86400,
  "version": "4.0.0"
}

Queue statistics — job counts by status and queue name. Includes recent failures. Requires admin role.

Server-Sent Events stream for real-time event monitoring. Pass JWT as query parameter. Uses Redis pub/sub when available, falls back to database polling.

// JavaScript
const es = new EventSource(`/api/v4/stream?app_id=1&token=${jwt}`);
es.onmessage = (e) => {
  const events = JSON.parse(e.data);
  console.log('New events:', events);
};