Channel Rules
How raw traffic gets a channel name — and how to change the mapping without guessing what it will re-label.
A channel rule maps raw traffic — referrer, UTM source and medium, click ids — onto one of the workspace's channel names ("Paid Social", "Organic Search", "Direct"). Every breakdown, every filter and every report that says channel is reading the result.
Rules are ordered: the first match wins, so priority is part of the rule, not a tie-break.
Look before you write
The three read/preview routes exist because a rule change re-labels history, not just new traffic:
GET /api/v1/channel-rules/suggestions
POST /api/v1/channel-rules/match-count
POST /api/v1/channel-rules/diffsuggestionsproposes rules for traffic that is currently unclassified — the honest starting point when a large share of sessions lands in "Direct" or "Other".match-countanswers "how much traffic would this one candidate match".diffprojects what a whole candidate rule set would re-label, which is the only one that catches a new rule stealing traffic from an existing one.
Suggestions read the ephemeral buffer
Channel-rule suggestions are computed from session-grain data in the Ephemeral Buffer, whose retention is 30 days. A window longer than that is clamped, and the response says so. Conversion-definition suggestions are different — they read a durable table. See the range invariant.
Writing
POST /api/v1/channel-rules
PATCH /api/v1/channel-rules/{id}
DELETE /api/v1/channel-rules/{id}
POST /api/v1/channel-rules/reorder
POST /api/v1/channel-taxonomyreorder swaps two rules' priorities atomically — reordering by two
PATCH calls leaves a window in which both rules hold the same priority, and
the classifier is order-dependent.
POST /api/v1/channel-taxonomy adds a channel name to the workspace. A rule
can only point at a channel that exists.
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/channel-rules | List the profile's channel-classification rules and the channel taxonomy |
POST | /api/v1/channel-rules | Create one channel-classification rule |
PATCH | /api/v1/channel-rules/{id} | Update one channel-classification rule |
DELETE | /api/v1/channel-rules/{id} | Delete one channel-classification rule |
POST | /api/v1/channel-rules/diff | Project what a whole candidate rule set would re-label |
POST | /api/v1/channel-rules/match-count | Count how much traffic one candidate rule would match |
POST | /api/v1/channel-rules/reorder | Swap two rules' priorities atomically |
GET | /api/v1/channel-rules/suggestions | Suggest channel rules for traffic that is currently unclassified |
POST | /api/v1/channel-taxonomy | Add a channel to this workspace's taxonomy |
Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.