SDKs & Libraries

Official and community libraries for integrating with Flameup

Overview

While you can use Flameup's REST API directly, we provide SDKs and libraries to make integration easier.

REST API

All Flameup functionality is available through our REST API. Use standard HTTP clients in any language:

JavaScript/Node.js

Use fetch or axios

Python

Use requests or httpx

Any Language

Standard HTTP client

JavaScript / Node.js

Using Fetch (Recommended)

Modern JavaScript includes fetch by default:

// flare.js - Simple Flameup wrapper
class Flameup {
  constructor(apiKey, workspaceId) {
    this.apiKey = apiKey;
    this.workspaceId = workspaceId;
    this.baseUrl = 'https://api.flameup.ai/api/v1';
  }

  // Workspace-scoped request (used by push and other automation endpoints)
  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}/workspaces/${this.workspaceId}${endpoint}`;
    return this._send(url, options);
  }

  // Workspace-agnostic request (the People API-key surface lives at /api/v1/people)
  async apiRequest(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    return this._send(url, options);
  }

  async _send(url, options = {}) {
    const response = await fetch(url, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
        ...options.headers
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Request failed');
    }

    return response.json();
  }

  // People (API key targets the workspace-agnostic /api/v1/people path)
  async identifyUser(userId, traits = {}) {
    return this.apiRequest('/people', {
      method: 'POST',
      body: JSON.stringify({ userId, traits })
    });
  }

  async getUser(userId) {
    // userId is the external user ID you assigned; returns the person object
    return this.apiRequest(`/people/${userId}`);
  }

  // Events (uses /api/v1/track endpoint directly)
  async track(externalId, event, parameters = {}) {
    const response = await fetch('https://api.flameup.ai/api/v1/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify({
        external_id: externalId,
        event,
        parameters,
        timestamp: new Date().toISOString()
      })
    });
    return response.json();
  }

  // Push notifications
  async sendPush(personId, title, body, options = {}) {
    return this.request('/push/send', {
      method: 'POST',
      body: JSON.stringify({
        person_id: personId,
        title,
        body,
        ...options
      })
    });
  }
}

// Usage
const flare = new Flameup('ws_live_abc12345_abc123.your_secret_here', 'ws_abc123');

await flare.identifyUser('user_123', {
  email: 'jane@example.com',
  first_name: 'Jane'
});

await flare.track('user_123', 'page_viewed', {
  page: '/pricing'
});

Using Axios

import axios from 'axios';

const flare = axios.create({
  baseURL: 'https://api.flameup.ai/api/v1',
  headers: {
    'Authorization': 'Bearer ws_live_abc12345_abc123.your_secret_here'
  }
});

// Identify user (People API key surface is workspace-agnostic)
await flare.post('/people', {
  userId: 'user_123',
  email: 'jane@example.com',
  traits: { first_name: 'Jane' }
});

// Track event (uses /track endpoint)
await flare.post('/track', {
  external_id: 'user_123',
  event: 'purchase_completed',
  parameters: { amount: 99.99 }
});

Python

Using Requests

import requests
from datetime import datetime

class Flameup:
    def __init__(self, api_key, workspace_id):
        self.api_key = api_key
        self.workspace_id = workspace_id
        self.base_url = 'https://api.flameup.ai/api/v1'
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}'
        })

    def _url(self, endpoint):
        # Workspace-scoped URL, used by push and other automation endpoints
        return f'{self.base_url}/workspaces/{self.workspace_id}{endpoint}'

    def identify(self, user_id, traits=None):
        """Create or update a user profile (People API key surface is workspace-agnostic)."""
        return self.session.post(
            f'{self.base_url}/people',
            json={'userId': user_id, 'traits': traits or {}}
        ).json()

    def track(self, external_id, event, parameters=None):
        """Track a user event (uses /api/v1/track endpoint)."""
        return self.session.post(
            f'{self.base_url}/track',
            json={
                'external_id': external_id,
                'event': event,
                'parameters': parameters or {},
                'timestamp': datetime.utcnow().isoformat() + 'Z'
            }
        ).json()

    def send_push(self, person_id, title, body, **options):
        """Send a push notification."""
        return self.session.post(
            self._url('/push/send'),
            json={
                'person_id': person_id,
                'title': title,
                'body': body,
                **options
            }
        ).json()

# Usage
flare = Flameup('ws_live_abc12345_abc123.your_secret_here', 'ws_abc123')

flare.identify('user_123', {
    'email': 'jane@example.com',
    'first_name': 'Jane'
})

flare.track('user_123', 'page_viewed', {'page': '/pricing'})

Using HTTPX (Async)

import httpx
from datetime import datetime

class AsyncFlameup:
    def __init__(self, api_key, workspace_id):
        self.api_key = api_key
        self.workspace_id = workspace_id
        self.base_url = 'https://api.flameup.ai/api/v1'
        self.client = httpx.AsyncClient(
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {api_key}'
            }
        )

    async def identify(self, user_id, traits=None):
        # People API key surface is workspace-agnostic (/api/v1/people)
        response = await self.client.post(
            f'{self.base_url}/people',
            json={'userId': user_id, 'traits': traits or {}}
        )
        return response.json()

    async def track(self, external_id, event, parameters=None):
        response = await self.client.post(
            f'{self.base_url}/track',
            json={
                'external_id': external_id,
                'event': event,
                'parameters': parameters or {},
                'timestamp': datetime.utcnow().isoformat() + 'Z'
            }
        )
        return response.json()

# Usage
import asyncio

async def main():
    flare = AsyncFlameup('ws_live_abc12345_abc123.your_secret_here', 'ws_abc123')

    await flare.identify('user_123', {'email': 'jane@example.com'})
    await flare.track('user_123', 'page_viewed', {'page': '/pricing'})

asyncio.run(main())

Mobile SDKs

iOS (Swift)

import Foundation

class Flameup {
    private let apiKey: String
    private let workspaceId: String
    private let baseURL = "https://api.flameup.ai/api/v1"

    init(apiKey: String, workspaceId: String) {
        self.apiKey = apiKey
        self.workspaceId = workspaceId
    }

    func identify(userId: String, traits: [String: Any] = [:]) async throws {
        let url = URL(string: "\(baseURL)/people")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.httpBody = try JSONSerialization.data(withJSONObject: [
            "userId": userId,
            "traits": traits
        ])

        let (_, response) = try await URLSession.shared.data(for: request)
        guard (response as? HTTPURLResponse)?.statusCode == 200 else {
            throw FlameupError.requestFailed
        }
    }

    func track(externalId: String, event: String, parameters: [String: Any] = [:]) async throws {
        let url = URL(string: "\(baseURL)/track")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.httpBody = try JSONSerialization.data(withJSONObject: [
            "external_id": externalId,
            "event": event,
            "parameters": parameters,
            "timestamp": ISO8601DateFormatter().string(from: Date())
        ])

        let (_, response) = try await URLSession.shared.data(for: request)
        guard (response as? HTTPURLResponse)?.statusCode == 200 else {
            throw FlameupError.requestFailed
        }
    }
}

enum FlameupError: Error {
    case requestFailed
}

// Usage
let flare = Flameup(apiKey: "ws_live_abc12345_abc123.your_secret_here", workspaceId: "ws_abc123")

Task {
    try await flare.identify(userId: "user_123", traits: [
        "email": "jane@example.com",
        "first_name": "Jane"
    ])

    try await flare.track(externalId: "user_123", event: "app_opened")
}

Android (Kotlin)

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

class Flameup(
    private val apiKey: String,
    private val workspaceId: String
) {
    private val client = OkHttpClient()
    private val baseUrl = "https://api.flameup.ai/api/v1"
    private val jsonMediaType = "application/json".toMediaType()

    suspend fun identify(userId: String, traits: Map<String, Any> = emptyMap()) {
        withContext(Dispatchers.IO) {
            val body = JSONObject().apply {
                put("userId", userId)
                put("traits", JSONObject(traits))
            }

            val request = Request.Builder()
                .url("$baseUrl/people")
                .post(body.toString().toRequestBody(jsonMediaType))
                .header("Authorization", "Bearer $apiKey")
                .build()

            client.newCall(request).execute()
        }
    }

    suspend fun track(externalId: String, event: String, parameters: Map<String, Any> = emptyMap()) {
        withContext(Dispatchers.IO) {
            val body = JSONObject().apply {
                put("external_id", externalId)
                put("event", event)
                put("parameters", JSONObject(parameters))
                put("timestamp", java.time.Instant.now().toString())
            }

            val request = Request.Builder()
                .url("$baseUrl/track")
                .post(body.toString().toRequestBody(jsonMediaType))
                .header("Authorization", "Bearer $apiKey")
                .build()

            client.newCall(request).execute()
        }
    }
}

// Usage
val flare = Flameup("ws_live_abc12345_abc123.your_secret_here", "ws_abc123")

lifecycleScope.launch {
    flare.identify("user_123", mapOf(
        "email" to "jane@example.com",
        "first_name" to "Jane"
    ))

    flare.track(externalId = "user_123", event = "app_opened")
}

Flutter (Dart)

# pubspec.yaml
dependencies:
  flameup_flutter:
    git:
      url: https://github.com/flameupAI/flare.git
      path: sdk/flutter

import 'package:flameup_flutter/flameup.dart';

// 1. Initialize
final flameup = Flameup(FlameupConfig(
  apiKey: 'ws_live_abc12345_abc123.your_secret_here',
));

// 2. Identify user on login
final person = await flameup.identify(
  userId: 'user_123',
  email: 'jane@example.com',
  traits: {'first_name': 'Jane', 'plan': 'premium'},
);

// 3. Track events (zero latency — queued & batched automatically)
flameup.track(
  externalId: 'user_123',
  event: 'add_to_cart',
  parameters: {'product_id': 'prod_001', 'price': 49.99},
);

// 4. Register device for push notifications
await flameup.registerDevice(
  personId: person.id!,
  token: fcmToken,
  platform: 'ios',
  deviceInfo: DeviceInfo(
    deviceName: 'iPhone 15 Pro',
    appVersion: '2.1.0',
  ),
);

cURL Examples

For quick testing or shell scripts:

# Set your credentials
export FLARE_API_KEY="ws_live_abc12345_abc123.your_secret_here"
export WORKSPACE_ID="ws_abc123"

# Identify a user (People API key surface is workspace-agnostic)
curl -X POST "https://api.flameup.ai/api/v1/people" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FLARE_API_KEY" \
  -d '{"userId": "user_123", "email": "jane@example.com"}'

# Track an event
curl -X POST "https://api.flameup.ai/api/v1/track" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FLARE_API_KEY" \
  -d '{"external_id": "user_123", "event": "test_event"}'

OpenAPI Specification

Use our OpenAPI spec to generate clients in any language.

Spec URL: GET https://api.flameup.ai/api/v1/docs/openapi — the spec is served as JSON (not a static openapi.yaml).
Access: This endpoint is protected by monitoring basic-auth, so download the spec with credentials first and point your generator at the local file rather than the URL.
Generators: Use OpenAPI Generator or similar tools

# Download the spec (monitoring basic-auth required)
curl -u "$MONITORING_USER:$MONITORING_PASS" \
  "https://api.flameup.ai/api/v1/docs/openapi" -o openapi.json

# Generate a TypeScript client from the downloaded spec
openapi-generator generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./flare-client

Was this page helpful?