API Reference¶

Welcome to the Helomatic API documentation. Our REST API provides comprehensive endpoints for authentication, monitoring, AI integration, and data management.

Base URL¶

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

API Versioning¶

The Helomatic API uses version v1 and is accessed through the base URL. Future versions will be made available with proper migration guides.

• Current Version: v1.0.0
• API Stability: Production-ready
• Breaking Changes: Will be announced 30 days in advance

Request/Response Format¶

Content Type¶

All API requests must include the Content-Type: application/json header for POST/PUT/PATCH requests.

Response Structure¶

{
  "success": true,
  "data": { /* response data */ },
  "message": "Success message",
  "timestamp": "2025-08-22T18:19:49.258Z"
}

Error Response Structure¶

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { /* additional error context */ },
  "timestamp": "2025-08-22T18:19:49.258Z"
}

Authentication¶

Helomatic uses JWT (JSON Web Tokens) with refresh token support for secure API access.

Authentication Flow¶

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: POST /api/auth/login
    API->>Database: Validate credentials
    Database-->>API: User data
    API-->>Client: Access + Refresh tokens

    Note over Client: Store tokens securely

    Client->>API: Authenticated request + JWT
    API->>API: Validate JWT
    API-->>Client: Protected resource

    Note over Client: When access token expires

    Client->>API: POST /api/auth/refresh
    API-->>Client: New access token

Headers¶

Include the following header in authenticated requests:

Authorization: Bearer <your_access_token>

Rate Limiting¶

The API implements progressive rate limiting based on user tiers:

Rate Limit Headers¶

X-Ratelimit-Limit: 1000
X-Ratelimit-Remaining: 950
X-Ratelimit-Reset: 1755886860000
X-Ratelimit-Retry-After: 3600

Error Codes¶

Response Codes¶

Success Codes¶

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 204 No Content: Request successful, no content returned

Error Codes¶

• 400 Bad Request: Invalid request format or parameters
• 401 Unauthorized: Authentication credentials missing or invalid
• 403 Forbidden: Insufficient permissions for the requested resource
• 404 Not Found: Requested resource doesn't exist
• 422 Unprocessable Entity: Request format valid but content invalid
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Unexpected server error
• 503 Service Unavailable: Service temporarily unavailable

API Endpoints Quick Reference¶

System Endpoints¶

• GET /health - Health check
• GET /status - System status
• GET /metrics - Prometheus metrics

Authentication¶

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/refresh - Token refresh
• POST /api/auth/logout - User logout

Monitoring¶

• GET /api/monitoring/sources - List monitoring sources
• POST /api/monitoring/sources - Create monitoring source
• GET /api/monitoring/sources/{id} - Get specific source
• PUT /api/monitoring/sources/{id} - Update monitoring source
• DELETE /api/monitoring/sources/{id} - Delete monitoring source

AI Integration¶

• POST /api/ai/chat - AI chat completion
• POST /api/ai/completion - Text completion
• GET /api/ai/models - Available AI models
• GET /api/ai/usage - AI usage statistics

Data Management¶

• POST /api/data/enrichment - Enrich data with AI
• GET /api/data/jobs - List data processing jobs
• GET /api/data/jobs/{id} - Get specific job status

WebSocket Support¶

For real-time features, connect to our WebSocket endpoint:

wss://helomatic-api-prod.ernijs-ansons.workers.dev/ws

WebSocket Authentication¶

// Include JWT in connection headers
const ws = new WebSocket('wss://api.helomatic.com/ws', [], {
  headers: {
    'Authorization': 'Bearer <your_access_token>'
  }
});

SDKs and Libraries¶

Official SDKs¶

• JavaScript/TypeScript: npm install @helomatic/sdk
• Python: pip install helomatic-sdk
• Go: go get github.com/helomatic/sdk-go

Community SDKs¶

• PHP: Available on GitHub
• Ruby: Available as gem
• Java: Maven package available

Testing¶

Sandbox Environment¶

Test your integration using our sandbox:

https://sandbox.helomatic.com/api

Postman Collection¶

Import our Postman collection for easy testing.

cURL Examples¶

Basic health check:

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

Authenticated request:

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

Continue to Authentication for detailed authentication implementation, or explore specific Endpoints for comprehensive API documentation.