Growlycs API Documentation

Authentication

API Key Authentication

All API requests require an API key to be included in the request header:

X-API-Key: your_api_key

Core Endpoints

Identify API

POST/api/identify

This endpoint is called when a user signs up or updates their profile.

Request Body

{
  "user_id": "unique_user_id",
  "email": "user@example.com",
  "name": "John Doe",
  "properties": {
    "plan": "premium",
    "company": "Acme Inc"
  }
}

Response

{
  "success": true,
  "message": "User created successfully",
  "user_id": "unique_user_id"
}

Track API

Record meaningful user events for signed-up users

POST/api/track

This endpoint focuses on four key user interactions: page views, button clicks, form submissions, and user inputs.

Request Body

{
  "user_id": "unique_user_id",
  "event_name": "viewed_pricing_page",
  "event_type": "page_view",
  "session_id": "optional_session_id",
  "properties": {
    "url": "/pricing",
    "title": "Pricing Plans"
  }
}

Response

{
  "success": true,
  "message": "Event recorded successfully",
  "session_id": "session_id_value"
}

Supported Event Types

page_view - Requires url and title properties
button_click - Requires element_text or element_type properties
form_submit - Requires form_id or form_action properties
user_input - Requires at least one of: input_id, input_name, or input_type properties

Script Installed API

Verify script installation and configuration

GET/api/script-installed

This endpoint confirms that the tracking script is properly installed and configured.

Response

{
  "success": true,
  "organization_id": "org_123",
  "script_version": "1.0.0"
}

AI-Powered Analytics Endpoints

Calculate Churn API

Analyze user behavior patterns to predict churn risk

GET/api/calculate-churn

This endpoint uses machine learning to evaluate user engagement data and assign a churn risk score.

Response

{
  "success": true,
  "stats": {
    "totalUsers": 100,
    "processedUsers": 100,
    "successfulUsers": 98,
    "failedUsers": 2,
    "predictions": [...]
  }
}

Nudge API

Generate personalized messages for users at risk of churning

POST/api/nudge

This endpoint generates personalized, contextual messages to re-engage users at risk of churning.

Request Body

{
  "user_id": "unique_user_id",
  "template_id": "template_123",
  "custom_context": {
    "feature": "dashboard",
    "last_action": "viewed_reports"
  }
}

Response

{
  "success": true,
  "nudge_id": "nudge_456",
  "content": "Hi John, we noticed you haven't explored the new dashboard features yet. Check out our latest reports for valuable insights!",
  "user_id": "unique_user_id"
}

Alert Founder API

Create actionable alerts for founders

POST/api/alert-founder

This endpoint generates actionable alerts for founders about important user behavior patterns.

Response

{
  "success": true,
  "alert_id": "alert_789",
  "alert_type": "high_value_user_at_risk",
  "user_id": "unique_user_id",
  "priority": "high",
  "message": "High-value customer at risk of churning. Last active 7 days ago.",
  "recommended_actions": [
    "Send personalized email",
    "Offer extended trial of premium features"
  ]
}

Utility Endpoints

Health Check API

Verify API service status

GET/api/health-check

This endpoint checks the health status of the API service and its dependencies.

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-07-20T22:35:00Z",
  "services": {
    "database": "connected",
    "ml_server": "connected"
  }
}

Sessions End Inactive API

Close inactive user sessions

GET/api/sessions/end-inactive

This endpoint closes sessions that have been inactive for a specified period.

Response

{
  "success": true,
  "sessions_closed": 42,
  "inactivity_threshold_minutes": 30
}

ML Server Integration

Machine Learning Server

Growlycs uses a dedicated ML server for churn prediction and analytics. The ML server provides the following endpoints:

POST /api/v1/predict-churn - Single user prediction
POST /api/v1/batch-predict - Batch prediction for multiple users
GET /api/v1/model-info - Get model metadata
GET /api/v1/health - Health check endpoint
POST /api/v1/reload-model - Reload the model without restarting

The ML server is configured via environment variables and requires an API key for authentication.