Integration API Documentation

Overview

The Integration API provides programmatic access to core platform functionality including data imports, report generation, automation execution, and data preparation. The API supports authentication via Integration API Keys, allowing for secure server-to-server communication and automated workflows.

Base URL

https://integration.{region}.flarelight.cloud

Authentication

The Integration API uses API Key authentication. API keys must be included in the X-Api-Key header of each request.

Headers Required

API Key Types

• User API Keys: Associated with a specific user account and inherit that user's permissions
• System API Keys: Provide broader access for system-level integrations

Example Request

curl -X GET \
  "https://integration.{region}.flarelight.cloud/Import/All" \
  -H "X-Api-Key: your-api-key-here" \
  -H "X-Subscription-Id: your-subscription-id" \
  -H "Content-Type: application/json"

Response Format

All API responses follow a consistent format:

{
  "data": {},
  "messages": []
}

• data: Contains the response payload
• messages: Array of informational or error messages

Endpoints

Data Import

Get All Data Imports

Retrieve all data imports accessible to the authenticated user.

Get Data Import Data

Retrieve paginated data from a specific import.

Import Data

Create a new data import or update an existing one.

Automation

Execute Automation

Trigger execution of an automation configured for Integration API triggers.

Data Preparation

Get All Data Preparations

Retrieve all data preparation models accessible to the authenticated user.

Execute Data Preparation

Trigger execution of a data preparation model.

Reports

Get All Reports

Retrieve all generated reports accessible to the authenticated user.

Generate Report

Trigger generation of a report.

Get Chart Data

Retrieve chart data for custom reporting.

Error Handling

The API uses standard HTTP status codes:

• 200 OK: Request successful
• 400 Bad Request: Invalid request parameters or data
• 401 Unauthorized: Invalid API key or insufficient permissions
• 403 Forbidden: Feature not enabled or access denied
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

Rate Limiting

API requests are subject to rate limiting based on your subscription tier. Rate limit information is included in response headers:

• X-RateLimit-Limit: Requests per minute allowed
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Time when rate limit resets

SDKs and Examples

Python Example

import requests

class IntegrationAPI:
    def __init__(self, api_key, subscription_id, base_url="https://integration.{region}.flarelight.cloud"):
        self.api_key = api_key
        self.subscription_id = subscription_id
        self.base_url = base_url
        
    def _headers(self):
        return {
            'X-Api-Key': self.api_key,
            'X-Subscription-Id': self.subscription_id,
            'Content-Type': 'application/json'
        }
    
    def import_data(self, data, name=None, description=None, send_events=True):
        payload = {
            'data': data,
            'name': name,
            'description': description,
            'sendEvents': send_events
        }
        
        response = requests.post(
            f"{self.base_url}/Import/Data",
            headers=self._headers(),
            json=payload
        )
        
        return response.json()

# Usage Example
api = IntegrationAPI('your-api-key', 'your-subscription-id')
result = api.import_data(data={'records': [{'name': 'John Doe'}]})
print(f"Import ID: {result['data']['id']}")

JavaScript/Node.js Example

class IntegrationAPI {
    constructor(apiKey, subscriptionId, baseUrl = 'https://integration.{region}.flarelight.cloud') {
        this.apiKey = apiKey;
        this.subscriptionId = subscriptionId;
        this.baseUrl = baseUrl;
    }
    
    _headers() {
        return {
            'X-Api-Key': this.apiKey,
            'X-Subscription-Id': this.subscriptionId,
            'Content-Type': 'application/json'
        };
    }
    
    async importData(data, name = null, description = null, sendEvents = true) {
        const payload = { data, name, description, sendEvents };
        
        const response = await fetch(`${this.baseUrl}/Import/Data`, {
            method: 'POST',
            headers: this._headers(),
            body: JSON.stringify(payload)
        });
        
        return await response.json();
    }
}

// Usage Example
const api = new IntegrationAPI('your-api-key', 'your-subscription-id');
const result = await api.importData({records: [{name: 'John Doe'}]});
console.log(`Import ID: ${result.data.id}`);

Best Practices

Security

• Store API keys securely and never expose them in client-side code
• Use environment variables or secure key management systems
• Rotate API keys regularly
• Use System-level keys only when necessary

Performance

• Implement pagination when retrieving large datasets
• Use appropriate batch sizes for data imports (recommended: 1000-5000 records per request)
• Cache frequently accessed data locally when possible
• Monitor rate limits and implement backoff strategies

Troubleshooting

Common Issues

• 401 Unauthorized: Verify API key is correct and active, check subscription ID validity
• 403 Forbidden: Check if required features are enabled for your subscription
• 400 Bad Request: Validate request payload format and required fields
• Rate Limiting: Implement exponential backoff and monitor rate limit headers