Core Concepts

Understanding these building blocks will help you make the most of SegOps.

Tenants#

Every SegOps resource — segments, events, connectors, API keys — belongs to a tenant. A tenant represents your company or product workspace and is identified by a short lowercase slug (e.g., acme). Data is fully isolated between tenants at both the application and database layers.

A single user account can belong to multiple tenants with different roles (Owner, Admin, Member, Viewer). When using API keys, each key is scoped to exactly one tenant.

Events#

Events are the fundamental unit of data in SegOps. An event is an immutable behavioral record that captures something a user did — a purchase, a page view, a signup, a search. Events are persisted to our realtime analytics warehouse (ClickHouse) for high-throughput analytical queries.

Every event has four core fields:

• user_id — your unique identifier for the user (email, UUID, etc.)
• event_type — a snake_case label like order_placed or page_viewed
• occurred_at — ISO 8601 timestamp (defaults to server receive time)
• payload — an arbitrary JSON object with event-specific properties

User Properties#

User properties are persistent traits like email, plan, or company. They are set by sending a special context_identified event. The payload of the most-recent context_identifiedevent for each user is treated as that user's current properties. These are queryable as user_property conditions in segment rules.

Segments#

A segment is a named, rule-based audience. It defines a set of conditions that a user must satisfy to be a member. Segments are re-computed asynchronously, and membership is stored as a flat list of (user_id, computed_at) rows in the analytics warehouse for sub-millisecond read latency.

There are three segment types:

• rule — defined by explicit conditions (visual or JSON)
• ai — definition generated by the AI builder from natural language
• lookalike — audience expansion based on a seed segment (coming soon)

Segment DSL#

Under the hood, every segment definition is a JSON document called the Segment DSL. It has a logic key (AND or OR) and a conditions array. Each condition has a type field that determines which other fields are required.

At compute time, the DSL is compiled into an analytics SQL query. The visual rule builder and the AI builder both produce valid DSL JSON. You can also write or edit it directly via the API.

Membership Computation#

When you trigger a compute (via the UI or POST /api/segments/<id>/compute/), SegOps dispatches a background task. The worker compiles the segment DSL into an analytics query, runs it against the events table, and writes the results to the segment_memberships table.

Computation is designed for incremental (delta) updates — only users whose event history changed since the last compute are re-evaluated. For large tenants, a full recompute may take a few minutes; delta recomputes are typically under 10 seconds.

Activation#

Activation connectors push segment membership changes to external platforms after each recompute. When a connector is set to active, SegOps automatically diffs the previous and current membership and calls the platform API to add new members and remove exited members.

Supported platforms: Klaviyo (List sync), Braze (Subscription Groups), TalonOne (Audiences), plus CSV/Parquet file export.

API Keys vs JWT#

SegOps supports two authentication modes:

• JWT (Bearer token) — obtained via POST /api/auth/token/ with email/password. Use for user-initiated calls from your frontend or internal tools. Expires in 60 minutes. Refresh with /api/auth/token/refresh/.
• API Key (ApiKey header) — long-lived server-to-server credential. Use for event ingestion, membership checks, and CI/CD scripts. Issued per-tenant, revocable at any time from Settings → API Keys.