Changelog

Send policy: rolling-window cap, validated on write

The workspace send policy (settings.send_policy) gains a rolling-window frequency cap alongside the existing daily cap and quiet hours:

• max_pushes_per_window + window_hours — at most N pushes per user in any sliding window of 1–168 hours, counted in absolute time (no calendar or timezone reset, unlike the daily cap's local-midnight boundary). The two fields are set together — both > 0 to enable, both 0 to disable.
• A send blocked by it returns the same 200 with "status": "policy_suppressed" as the other rules, on transactional sends and journey pushes alike.
• A journey push node's bypass_frequency_cap skips both frequency caps — daily and rolling. Quiet hours remain unbypassable by anything.

The workspace-settings write path now validates send_policy instead of storing whatever arrives: PUT /workspaces/{id} rejects a malformed policy with 400 INVALID_SEND_POLICY — quiet-hours times must be HH:MM, a non-empty timezone must be a real IANA name (empty means UTC), caps must be >= 0, window_hours must be within 0–168, and the window pair must be set both-or-neither. Previously a bad policy was silently stored and then failed open at send time.

Breaking: event triggers name a list of events

trigger_config.event_name (one string) is now event_names (an array — any listed event fires the campaign). Existing campaigns were migrated in place; a config still sending the singular key is rejected with event_name was replaced by event_names rather than silently accepted, since the trigger lookup only matches the array.

Also in this release:

• first_occurrence (trigger option) — fire only the first time your workspace has ever seen the event for a person. Implies once-only entry and cannot be combined with max_per_user > 1.
• Count-based conditions — event-history conditions gain performed_count_gte / _lte / _eq / _between, with bounds in the condition value (count, count_max). "The 4th or 5th time" no longer needs a client-side counter on the event.
• Unknown filter operators now fail closed and are rejected at campaign activation, instead of matching everything.
• max_per_user is enforced by the database — concurrent duplicate events can no longer double-enroll a person.
• Segment DELETE returns 409 with the blocking campaign names when the segment is still in use (previously a bare 500).
• Template namespaces unified — {{user.traits.x}} and {{user.properties.x}} both read the /identify attribute bag.

Breaking: external_id replaces the person UUID

Two API-key surfaces changed the identifier they accept, so that every API-key route now takes the identifier you assign rather than mixing it with Flameup's internal person UUID.

Note the push-send path: unlike the device routes, the API-key push-send route is workspace-scoped (/api/v1/workspaces/{workspace_id}/push/send). Only the body field changed in this release; there has never been a bare /api/v1/push/send.

Why: the mismatch was not cosmetic. An app registered a push token against a UUID while its events arrived keyed by external_id, so the token attached to a different person record than campaigns resolved — and the push silently went nowhere.

What to change: stop resolving a person UUID before these calls and pass the same user id you already send to /identify and /track. There is no lookup step to keep.

The Firebase-authenticated dashboard routes (/workspaces/{workspace_id}/people/{personId}/...) are unchanged and still take UUIDs, which is correct there — they read them from their own list views.

Flameup API v1.0.0 - General Availability

We're excited to announce the general availability of the Flameup API!

People API

• Create, read, update, and delete user profiles
• Upsert operations for seamless create-or-update workflows
• Batch operations for creating and updating multiple people in a single request
• Search and filter by email, external_id, status, and custom attributes
• Statistics endpoint for aggregate metrics

Events API

• Track user events with custom properties
• Query events by user, event name, and time range
• Events stored in ClickHouse for high-performance analytics

Devices API

• Register device tokens for iOS, Android and Web push
• Automatic token lifecycle management
• Support for device metadata (model, OS version, app version)

Campaigns

• Event-triggered campaigns
• API-initiated campaign triggering (POST /campaigns/{id}/trigger)
• Scheduled and dynamic-schedule campaigns

Campaigns are authored in the dashboard. The API triggers them; it does not create or edit them.

Messaging APIs

• Push notifications via FCM (iOS, Android and Web)
• Batch push sending

(This entry originally also claimed delivery-status reads and token suppression. Token suppression is implemented and functional: POST /workspaces/{workspace_id}/push/tokens/suppress writes a suppression (201 for a new row, 200 with already_suppressed: true when the token is already suppressed under that type) and DELETE /workspaces/{workspace_id}/push/tokens/suppress/{id} lifts it (404 for an unknown id or one belonging to another workspace). Both are gated by push:send, and every send is checked against those suppression rows. Of the delivery-status reads, only GET /workspaces/{workspace_id}/push/status/{message_id} (push:read) is implemented; the notification-history and analytics routes still answer 501 — see Transactional Push for what works today.)

Email and SMS are sent through campaigns and the dashboard, not through an API key.

Authentication

• API key authentication via Authorization: Bearer header
• Granular permissions system
• Key expiration and rotation

Developer Experience

• Comprehensive API documentation
• OpenAPI 3.0 specification
• Code examples in JavaScript, Python and Dart
• Rate limiting with informative headers