Skip to content

API Endpoints

Complete reference for all Helomatic API endpoints with request/response examples.

System Endpoints

Health Check

Check the API service health and availability.

GET /health

{
  "status": "healthy",
  "environment": "production",
  "timestamp": "2025-08-22T18:19:49.258Z",
  "version": "1.0.0"
}

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

System Status

Get detailed system status including component health.

GET /status

{
  "status": "operational",
  "environment": "production",
  "timestamp": "2025-08-22T18:19:58.088Z",
  "version": "1.0.0",
  "components": {
    "database": {
      "status": "operational",
      "latency": 596,
      "last_check": "2025-08-22T18:19:58.088Z"
    },
    "kv_storage": {
      "status": "operational",
      "latency": 55,
      "last_check": "2025-08-22T18:19:58.088Z"
    },
    "rate_limiter": {
      "status": "operational",
      "last_check": "2025-08-22T18:19:58.088Z"
    }
  },
  "security": {
    "headers_enabled": true,
    "cors_configured": true,
    "rate_limiting": "active",
    "ssl_enforced": true
  }
}

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

Metrics

Retrieve Prometheus-style metrics for monitoring.

GET /metrics

# HELP http_requests_total Total HTTP requests processed
# TYPE http_requests_total counter
http_requests_total{method="GET",status="200"} 1547
http_requests_total{method="POST",status="200"} 892
http_requests_total{method="POST",status="400"} 23

# HELP http_request_duration_seconds HTTP request latency
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 1205
http_request_duration_seconds_bucket{le="0.5"} 1456
http_request_duration_seconds_bucket{le="1.0"} 1502

curl -X GET \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/metrics

Authentication Endpoints

User Registration

Register a new user account.

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John Doe",
  "company": "Example Corp",
  "role": "user",
  "acceptTerms": true,
  "enableMFA": false
}

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John Doe",
      "company": "Example Corp",
      "role": "user",
      "verified": false,
      "created_at": "2025-08-22T18:30:15.123Z"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 3600,
      "token_type": "Bearer"
    }
  },
  "message": "Registration successful. Please verify your email."
}

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "John Doe",
    "company": "Example Corp",
    "role": "user",
    "acceptTerms": true
  }'

User Login

Authenticate a user and receive access tokens.

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "deviceFingerprint": "device_12345",
  "rememberDevice": true
}

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "last_login": "2025-08-22T18:35:20.456Z"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 3600,
      "token_type": "Bearer"
    },
    "session": {
      "session_id": "sess_abcdef123456",
      "expires_at": "2025-08-22T19:35:20.456Z"
    }
  },
  "message": "Login successful"
}

{
  "success": false,
  "error": "Invalid credentials",
  "code": "INVALID_CREDENTIALS",
  "details": {
    "attempts_remaining": 4,
    "lockout_time": null
  }
}

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

Token Refresh

Refresh an expired access token using a refresh token.

POST /api/auth/refresh
Content-Type: application/json
Authorization: Bearer <refresh_token>

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600,
    "token_type": "Bearer"
  },
  "message": "Token refreshed successfully"
}

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

Monitoring Endpoints

List Monitoring Sources

Get all monitoring sources for the authenticated user.

GET /api/monitoring/sources
Authorization: Bearer <access_token>

{
  "success": true,
  "data": {
    "sources": [
      {
        "id": "mon_1234567890",
        "name": "E-commerce Price Monitor",
        "url": "https://example-store.com/products/widget",
        "schedule": "hourly",
        "status": "active",
        "last_check": "2025-08-22T18:00:00.000Z",
        "next_check": "2025-08-22T19:00:00.000Z",
        "extractors": [
          {
            "type": "css",
            "selector": ".price",
            "name": "product_price",
            "last_value": "$29.99"
          }
        ],
        "created_at": "2025-08-20T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "has_more": false
    }
  }
}

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

Create Monitoring Source

Create a new monitoring source.

POST /api/monitoring/sources
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "name": "Competitor Price Tracker",
  "url": "https://competitor.com/product/123",
  "schedule": "daily",
  "extractors": [
    {
      "type": "css",
      "selector": ".price-current",
      "name": "current_price",
      "attribute": "data-price"
    },
    {
      "type": "xpath",
      "selector": "//span[@class='stock-status']/text()",
      "name": "stock_status"
    }
  ],
  "webhookUrl": "https://your-app.com/webhook/price-changed",
  "webhookEvents": ["data_changed", "error"],
  "retryAttempts": 3,
  "timeout": 30000,
  "tags": ["ecommerce", "pricing", "competitor"]
}

{
  "success": true,
  "data": {
    "source": {
      "id": "mon_0987654321",
      "name": "Competitor Price Tracker",
      "url": "https://competitor.com/product/123",
      "schedule": "daily",
      "status": "active",
      "extractors": [
        {
          "type": "css",
          "selector": ".price-current",
          "name": "current_price",
          "attribute": "data-price"
        }
      ],
      "webhook_url": "https://your-app.com/webhook/price-changed",
      "webhook_events": ["data_changed", "error"],
      "created_at": "2025-08-22T18:40:00.000Z",
      "next_check": "2025-08-23T18:40:00.000Z"
    }
  },
  "message": "Monitoring source created successfully"
}

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "name": "Competitor Price Tracker",
    "url": "https://competitor.com/product/123",
    "schedule": "daily",
    "extractors": [
      {
        "type": "css",
        "selector": ".price-current",
        "name": "current_price"
      }
    ]
  }'

AI Integration Endpoints

Chat Completion

Send a message to AI and receive a response.

POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful business automation assistant."
    },
    {
      "role": "user", 
      "content": "Help me create a workflow to automate customer onboarding."
    }
  ],
  "task": "automation",
  "options": {
    "temperature": 0.7,
    "max_tokens": 1000,
    "model": "gpt-4",
    "stream": false
  }
}

{
  "success": true,
  "data": {
    "response": {
      "role": "assistant",
      "content": "I'll help you create an automated customer onboarding workflow. Here's a comprehensive approach:\n\n1. **Welcome Email Sequence**\n   - Immediate welcome email with getting started guide\n   - Day 2: Product overview and key features\n   - Day 7: Success stories and best practices\n\n2. **Account Setup Automation**\n   - Automatic profile creation\n   - Default settings configuration\n   - Integration setup prompts\n\n3. **Progress Tracking**\n   - Onboarding completion milestones\n   - Automated check-ins at 30, 60, 90 days\n   - Usage analytics and recommendations\n\nWould you like me to detail any specific part of this workflow?"
    },
    "usage": {
      "tokens_used": 247,
      "model": "gpt-4",
      "cost": 0.00741
    },
    "conversation_id": "conv_abc123def456"
  }
}

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a workflow for customer onboarding"
      }
    ],
    "task": "automation"
  }'

Data Management Endpoints

Data Enrichment

Enrich data using AI-powered processing.

POST /api/data/enrichment
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "data": {
    "company": "TechCorp Inc",
    "email": "contact@techcorp.com",
    "website": "techcorp.com"
  },
  "enrichmentType": "company_details",
  "instructions": "Find company size, industry, and key contacts",
  "outputFormat": "json",
  "includeConfidence": true
}

{
  "success": true,
  "data": {
    "enriched_data": {
      "company": "TechCorp Inc",
      "email": "contact@techcorp.com",
      "website": "techcorp.com",
      "industry": "Software Development",
      "employee_count": "50-200",
      "founded": "2015",
      "headquarters": "San Francisco, CA",
      "revenue_range": "$10M-$50M",
      "key_contacts": [
        {
          "name": "John Smith",
          "role": "CEO",
          "email": "john@techcorp.com"
        },
        {
          "name": "Sarah Johnson", 
          "role": "CTO",
          "email": "sarah@techcorp.com"
        }
      ]
    },
    "confidence_scores": {
      "industry": 0.95,
      "employee_count": 0.82,
      "revenue_range": 0.67,
      "key_contacts": 0.89
    },
    "processing_time": 2.3,
    "sources_used": ["linkedin", "crunchbase", "company_website"]
  }
}

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/data/enrichment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "data": {
      "company": "TechCorp Inc",
      "website": "techcorp.com"
    },
    "enrichmentType": "company_details"
  }'

Error Handling Examples

Validation Error (400)

POST /api/auth/register
Content-Type: application/json

{
  "email": "invalid-email",
  "password": "123"
}

{
  "success": false,
  "error": "Invalid input",
  "code": "VALIDATION_ERROR",
  "details": {
    "errors": [
      "email: Invalid email format",
      "password: Password must be at least 8 characters",
      "name: Name is required",
      "acceptTerms: Must accept terms"
    ]
  },
  "timestamp": "2025-08-22T18:45:00.123Z"
}

Rate Limit Error (429)

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset_time": "2025-08-22T19:00:00.000Z",
    "retry_after": 900
  },
  "timestamp": "2025-08-22T18:45:00.123Z"
}

Authentication Error (401)

{
  "success": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {
    "message": "Valid access token required",
    "login_url": "/api/auth/login"
  },
  "timestamp": "2025-08-22T18:45:00.123Z"
}

For implementation details, see Authentication or explore our OpenAPI Specification.