HeliosDB Onboarding API Documentation

Complete REST API reference for the HeliosDB automated customer onboarding system.

Base URL

Production: https://api.heliosdb.com
Development: http://localhost:8080

Authentication

Most endpoints require authentication via API key:

Authorization: Bearer <api_key>

Endpoints

Create a new customer account with automatic provisioning.

Request Body:

{
  "email": "customer@example.com",
  "name": "John Doe",
  "password": "SecurePass123!",
  "company": "Acme Inc",
  "account_type": "trial"
}

Response (201 Created):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "customer@example.com",
    "account_type": "trial",
    "trial_end_date": "2025-02-08T00:00:00Z",
    "verification_email_sent": true,
    "credentials": {
      "database_url": "postgresql://user_...@db.heliosdb.com:5432/user_...",
      "api_key": "hdb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "username": "user_...",
      "host": "db.heliosdb.com",
      "port": 5432,
      "database": "user_..."
    },
    "quotas": {
      "max_connections": 25,
      "max_storage_gb": 10,
      "max_gpu_minutes_per_day": 60,
      "max_queries_per_day": 100000,
      "max_tables": 50,
      "max_indexes": 100,
      "backup_retention_days": 7
    }
  }
}

GET /verify-email?token=xxx

Verify email address using token sent via email.

Query Parameters:

token (required): Email verification token

Response (200 OK):

{
  "success": true,
  "data": "Email verified successfully"
}

POST /resend-verification

Resend email verification link.

Request Body:

{
  "email": "customer@example.com"
}

Response (200 OK):

{
  "success": true,
  "data": "Verification email sent"
}

Onboarding Progress

GET /onboarding/status/:user_id

Get current onboarding progress for a user.

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "total_steps": 5,
    "completed_steps": 2,
    "completion_percentage": 40.0,
    "current_step": {
      "step": "LoadSampleData",
      "step_number": 3,
      "title": "Load Sample Data",
      "description": "Load sample datasets to explore HeliosDB features",
      "instructions": [
        "Navigate to Sample Data section",
        "Choose a dataset (E-commerce, Analytics, etc.)",
        "Click 'Load Sample Data'"
      ]
    },
    "steps": [
      {
        "step": "VerifyEmail",
        "step_number": 1,
        "title": "Verify Email",
        "description": "Verify your email address to activate your account",
        "completed": true,
        "completed_at": "2025-01-25T10:30:00Z",
        "skipped": false
      },
      {
        "step": "ConnectToDatabase",
        "step_number": 2,
        "title": "Connect to Database",
        "description": "Connect to your HeliosDB instance",
        "completed": true,
        "completed_at": "2025-01-25T11:15:00Z",
        "skipped": false
      }
    ],
    "started_at": "2025-01-25T10:00:00Z",
    "completed_at": null,
    "estimated_time_remaining_minutes": 15
  }
}

POST /onboarding/complete-step

Mark an onboarding step as completed.

Request Body:

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "step": "load_sample_data"
}

Response (200 OK):

{
  "success": true,
  "data": "Step completed"
}

POST /onboarding/reset/:user_id

Reset onboarding progress (admin only).

Response (200 OK):

{
  "success": true,
  "data": "Onboarding reset"
}

Trial Management

GET /trial/status/:user_id

Get trial account status and usage information.

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "is_trial": true,
    "trial_start_date": "2025-01-25T00:00:00Z",
    "trial_end_date": "2025-02-08T23:59:59Z",
    "days_remaining": 14,
    "trial_expired": false,
    "usage_summary": {
      "total_queries": 1543,
      "total_connections": 45,
      "storage_used_gb": 2.3,
      "gpu_minutes_used": 12,
      "api_calls": 89
    },
    "conversion_eligible": true
  }
}

POST /trial/convert

Convert trial account to paid tier.

Request Body:

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "target_tier": "professional",
  "payment_method": "stripe",
  "billing_email": "billing@example.com"
}

Response (200 OK):

{
  "success": true,
  "data": "Trial converted successfully"
}

POST /trial/extend

Extend trial period (admin only).

Request Body:

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "extension_days": 7,
  "reason": "Customer requested extension for POC",
  "granted_by": "admin@heliosdb.com"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "old_end_date": "2025-02-08T23:59:59Z",
    "new_end_date": "2025-02-15T23:59:59Z",
    "extension_days": 7,
    "reason": "Customer requested extension for POC",
    "granted_by": "admin@heliosdb.com",
    "granted_at": "2025-01-25T15:30:00Z"
  }
}

Usage Tracking

GET /usage/:user_id

Get current usage statistics for a user.

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "period_start": "2025-01-01T00:00:00Z",
    "period_end": "2025-01-31T23:59:59Z",
    "queries_executed": 15432,
    "connection_count": 245,
    "data_storage_gb": 8.7,
    "gpu_minutes_used": 45,
    "api_calls": 892,
    "quotas": {
      "max_connections": 25,
      "max_storage_gb": 10,
      "max_gpu_minutes_per_day": 60,
      "max_queries_per_day": 100000
    },
    "usage_percentages": {
      "queries": 15.4,
      "connections": 980.0,
      "storage": 87.0,
      "gpu_minutes": 75.0
    },
    "warnings": [
      "Storage quota at 87.0% - consider upgrading"
    ]
  }
}

GET /usage/:user_id/report?start_date=…&end_date=…

Generate usage report for a date range.

Query Parameters:

start_date (required): ISO 8601 date (e.g., 2025-01-01T00:00:00Z)
end_date (required): ISO 8601 date

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-01-31T23:59:59Z",
    "daily_stats": [
      {
        "date": "2025-01-01",
        "queries": 432,
        "gpu_minutes": 5,
        "api_calls": 23
      },
      {
        "date": "2025-01-02",
        "queries": 589,
        "gpu_minutes": 8,
        "api_calls": 31
      }
    ]
  }
}

GET /billing/:user_id/estimate

Get billing estimate based on current usage.

Response (200 OK):

{
  "success": true,
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "account_type": "professional",
    "base_fee": 99.0,
    "overage_charges": 12.50,
    "total_estimate": 111.50,
    "breakdown": [
      {
        "description": "Professional Plan",
        "quantity": 1.0,
        "unit": "month",
        "unit_price": 99.0,
        "total": 99.0
      },
      {
        "description": "Additional Storage",
        "quantity": 50.0,
        "unit": "GB",
        "unit_price": 0.25,
        "total": 12.50
      }
    ]
  }
}

Admin Endpoints

GET /admin/metrics

Get system-wide onboarding metrics.

Headers:

Authorization: Bearer <admin_api_key>

Response (200 OK):

{
  "success": true,
  "data": {
    "total_signups": 1250,
    "active_trials": 340,
    "completed_onboardings": 875,
    "completion_rate": 70.0,
    "avg_completion_time_minutes": 42.5
  }
}

GET /admin/users?page=1&per_page=20

List all users (admin only).

Query Parameters:

page (optional): Page number (default: 1)
per_page (optional): Items per page (default: 20)

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "account_type": "trial",
      "status": "active",
      "created_at": "2025-01-25T10:00:00Z"
    }
  ]
}

Error Responses

All errors follow this format:

{
  "success": false,
  "data": null,
  "error": "Error message here"
}

HTTP Status Codes

200 OK - Successful request
201 Created - Resource created successfully
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required or failed
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists (e.g., duplicate email)
500 Internal Server Error - Server error

Common Error Messages

{
  "success": false,
  "error": "Invalid signup data: email must be a valid email address"
}

{
  "success": false,
  "error": "Email already exists: customer@example.com"
}

{
  "success": false,
  "error": "Token expired"
}

{
  "success": false,
  "error": "Not a trial account"
}

Rate Limiting

API requests are rate limited:

Authenticated requests: 1000 requests per hour
Unauthenticated requests: 100 requests per hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1643040000

Webhooks

Configure webhooks for events:

Events

user.signup - New user signup
trial.expiring - Trial expiring in 7/3/1 days
trial.expired - Trial has expired
trial.converted - Trial converted to paid
onboarding.completed - User completed onboarding
usage.quota_exceeded - Usage quota exceeded

Webhook Payload

{
  "event": "trial.expiring",
  "timestamp": "2025-01-25T15:30:00Z",
  "data": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "customer@example.com",
    "days_remaining": 3
  }
}

SDK Examples

JavaScript/TypeScript

import { HeliosDBOnboardingClient } from '@heliosdb/onboarding-sdk';

const client = new HeliosDBOnboardingClient({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.heliosdb.com'
});

// Sign up new customer
const signupResult = await client.signup({
  email: 'customer@example.com',
  name: 'John Doe',
  password: 'SecurePass123!',
  company: 'Acme Inc',
  accountType: 'trial'
});

// Get onboarding status
const status = await client.onboarding.getStatus(userId);

// Complete a step
await client.onboarding.completeStep(userId, 'load_sample_data');

Python

from heliosdb_onboarding import OnboardingClient

client = OnboardingClient(
    api_key='your_api_key',
    base_url='https://api.heliosdb.com'
)

# Sign up new customer
result = client.signup(
    email='customer@example.com',
    name='John Doe',
    password='SecurePass123!',
    company='Acme Inc',
    account_type='trial'
)

# Get trial status
status = client.trial.get_status(user_id)

cURL

# Sign up
curl -X POST https://api.heliosdb.com/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "password": "SecurePass123!",
    "company": "Acme Inc",
    "account_type": "trial"
  }'

# Get usage
curl https://api.heliosdb.com/usage/<user_id> \
  -H "Authorization: Bearer <api_key>"

Testing

Test API Keys

Use these test API keys in development:

Admin: test_admin_key_dev
User: test_user_key_dev

Postman Collection

Import the Postman collection: postman/heliosdb-onboarding.json

Support

For API support:

Email: api-support@heliosdb.com
Documentation: https://docs.heliosdb.com/api
Status Page: https://status.heliosdb.com

HeliosDB Onboarding API Documentation

HeliosDB Onboarding API Documentation

Base URL

Authentication

Endpoints

Signup & Authentication

POST /signup

GET /verify-email?token=xxx

POST /resend-verification

Onboarding Progress

GET /onboarding/status/:user_id

POST /onboarding/complete-step

POST /onboarding/reset/:user_id

Trial Management

GET /trial/status/:user_id

POST /trial/convert

POST /trial/extend

Usage Tracking

GET /usage/:user_id

GET /usage/:user_id/report?start_date=…&end_date=…

GET /billing/:user_id/estimate

Admin Endpoints

GET /admin/metrics

GET /admin/users?page=1&per_page=20

Error Responses

HTTP Status Codes

Common Error Messages

Rate Limiting

Webhooks

Events

Webhook Payload

SDK Examples

JavaScript/TypeScript

Python

cURL

Testing

Test API Keys

Postman Collection

Support