Skip to content

Getting Started

Welcome to Helomatic! This guide will walk you through setting up your account, making your first API calls, and integrating our platform into your workflows.

Quick Start Checklist

  • Create an account and verify your email
  • Generate API credentials
  • Make your first API call
  • Set up monitoring or AI integration
  • Configure webhooks (optional)

Account Registration

Step 1: Create Your Account

Register for a Helomatic account using our API:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your.email@company.com",
    "password": "SecurePassword123!",
    "name": "Your Name",
    "company": "Your Company",
    "role": "user",
    "acceptTerms": true
  }'

Expected Response: 

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "your.email@company.com",
      "name": "Your Name",
      "verified": false
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 3600
    }
  },
  "message": "Registration successful. Please verify your email."
}

Save Your Tokens

Store both the access_token and refresh_token securely. You'll need them for authenticated requests.

Step 2: Verify Your Account (Email Verification)

Check your email for a verification link. Once verified, your account will have full API access.

Authentication Setup

Understanding JWT Tokens

Helomatic uses JWT (JSON Web Tokens) for authentication:

  • Access Token: Used for API requests (expires in 1 hour)
  • Refresh Token: Used to generate new access tokens (expires in 30 days)
graph LR
    A[Login Request] --> B[Access Token + Refresh Token]
    B --> C[API Requests]
    C --> D{Token Expired?}
    D -->|Yes| E[Use Refresh Token]
    D -->|No| F[Continue API Calls]
    E --> G[New Access Token]
    G --> C

Making Authenticated Requests

Include the access token in the Authorization header:

curl -X GET \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Authorization: Bearer your_access_token_here"

Token Refresh Example

When your access token expires, use the refresh token:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your_refresh_token_here"
  }'

Your First API Calls

Let's start with some basic API calls to familiarize yourself with the platform.

1. Health Check

Verify the API is accessible:

curl https://helomatic-api-prod.ernijs-ansons.workers.dev/health

Expected Response: 

{
  "status": "healthy",
  "environment": "production",
  "version": "1.0.0"
}

2. System Status

Get detailed system information:

curl https://helomatic-api-prod.ernijs-ansons.workers.dev/status

3. User Login

Authenticate with your credentials:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your.email@company.com",
    "password": "SecurePassword123!"
  }'

Setting Up Your First Integration

Choose your primary use case to get started quickly:

Use Case: Monitor competitor prices, content changes, or availability.

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "name": "Competitor Price Monitor",
    "url": "https://competitor.com/product/123",
    "schedule": "hourly",
    "extractors": [
      {
        "type": "css",
        "selector": ".price",
        "name": "current_price"
      },
      {
        "type": "css",
        "selector": ".stock-status",
        "name": "availability"
      }
    ],
    "webhookUrl": "https://your-app.com/webhook/price-change"
  }'

Use Case: Add AI-powered conversations to your application.

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful customer service assistant."
      },
      {
        "role": "user",
        "content": "How do I reset my password?"
      }
    ],
    "task": "general",
    "options": {
      "temperature": 0.7,
      "max_tokens": 500
    }
  }'

Use Case: Enhance your data with AI-powered insights.

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/data/enrichment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "data": {
      "company": "Acme Corp",
      "website": "acmecorp.com"
    },
    "enrichmentType": "company_details",
    "includeConfidence": true
  }'

Development Environment Setup

Environment Variables

Create a .env file with your credentials:

# Helomatic API Configuration
HELOMATIC_API_URL=https://helomatic-api-prod.ernijs-ansons.workers.dev
HELOMATIC_ACCESS_TOKEN=your_access_token_here
HELOMATIC_REFRESH_TOKEN=your_refresh_token_here

# Optional: Webhook endpoint for receiving notifications
WEBHOOK_URL=https://your-app.com/webhooks/helomatic

SDK Installation

npm install @helomatic/sdk

import { HelomaticClient } from '@helomatic/sdk';

const client = new HelomaticClient({
  apiUrl: 'https://helomatic-api-prod.ernijs-ansons.workers.dev',
  accessToken: process.env.HELOMATIC_ACCESS_TOKEN
});

// Make your first API call
const health = await client.health();
console.log(health);

pip install helomatic-sdk

from helomatic import HelomaticClient

client = HelomaticClient(
    api_url="https://helomatic-api-prod.ernijs-ansons.workers.dev",
    access_token=os.getenv("HELOMATIC_ACCESS_TOKEN")
)

# Make your first API call
health = client.health()
print(health)

Create a bash script for easy testing:

#!/bin/bash
# helomatic-test.sh

API_URL="https://helomatic-api-prod.ernijs-ansons.workers.dev"
ACCESS_TOKEN="your_access_token_here"

# Function to make authenticated requests
helomatic_api() {
    curl -H "Authorization: Bearer $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         "$API_URL$1" \
         "${@:2}"
}

# Test health endpoint
echo "Testing health endpoint..."
curl "$API_URL/health"

# Test authenticated endpoint
echo "Testing monitoring sources..."
helomatic_api "/api/monitoring/sources"

Webhook Configuration

Set up webhooks to receive real-time notifications about monitoring changes, AI completions, or system events.

Webhook Endpoint Setup

Create an endpoint to receive Helomatic webhooks:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

// Webhook signature verification
function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

app.post('/webhooks/helomatic', (req, res) => {
  const signature = req.headers['x-helomatic-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, 'your_webhook_secret')) {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook data
  const { type, data } = req.body;

  switch (type) {
    case 'monitoring.data_changed':
      console.log('Data changed:', data);
      break;
    case 'ai.completion_ready':
      console.log('AI completion:', data);
      break;
    default:
      console.log('Unknown webhook type:', type);
  }

  res.status(200).send('OK');
});

app.listen(3000);

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)

def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/helomatic', methods=['POST'])
def helomatic_webhook():
    signature = request.headers.get('X-Helomatic-Signature')
    payload = request.get_data()

    if not verify_signature(payload, signature, 'your_webhook_secret'):
        abort(401)

    data = request.get_json()
    webhook_type = data.get('type')

    if webhook_type == 'monitoring.data_changed':
        print(f"Data changed: {data}")
    elif webhook_type == 'ai.completion_ready':
        print(f"AI completion: {data}")

    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

Register Your Webhook

Add webhook URLs when creating monitoring sources:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Monitor",
    "url": "https://example.com",
    "schedule": "hourly",
    "extractors": [...],
    "webhookUrl": "https://your-domain.com/webhooks/helomatic",
    "webhookEvents": ["data_changed", "error", "success"],
    "webhookSecret": "your_webhook_secret_here"
  }'

Testing Your Integration

Using Postman

  1. Import our Postman Collection
  2. Set your access token in the collection variables
  3. Test endpoints interactively

Using Our API Playground

Visit our interactive API playground at: https://api.helomatic.com/playground

Local Testing

Run tests against your integration:

# Test webhook endpoint locally
curl -X POST http://localhost:3000/webhooks/helomatic \
  -H "Content-Type: application/json" \
  -H "X-Helomatic-Signature: sha256=test_signature" \
  -d '{
    "type": "monitoring.data_changed",
    "data": {
      "source_id": "mon_123",
      "changes": [
        {
          "field": "current_price",
          "old_value": "$29.99",
          "new_value": "$24.99"
        }
      ]
    }
  }'

Rate Limiting

Understand and respect our rate limits:

Tier Requests/Hour Burst Limit
Free 100 10
Pro 1,000 50
Enterprise 10,000 200

Handling Rate Limits

async function makeAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Ratelimit-Retry-After');
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);

      // Wait and retry
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeAPIRequest(url, options);
    }

    return response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Next Steps

Now that you're set up, explore these advanced features:

  1. Monitoring Setup - Advanced monitoring configurations
  2. AI Integration - Deep dive into AI capabilities
  3. Security Best Practices - Secure your integration
  4. API Reference - Complete endpoint documentation

Getting Help

🎉 Congratulations! You're now ready to build amazing integrations with Helomatic. Start with our tutorials or dive into the API reference for advanced usage.