Skip to main content
The convention is the workspace’s answer to “what does a well-formed UTM value look like”. It has four settings, it applies to every link created in the workspace — from the console, the assistant, the API or the MCP — and it sits at the top of the Rules page, https://app.utmkit.co/rules.

​
The four settings

  • Casing: lower, upper or any.
  • Separator: the character between words, hyphen, underscore or any.
  • Required parameters: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content that a link may not leave out.
  • A violation: the mode. block refuses the link; warn creates it and reports the problem.
A value passes the format when it is words of letters a–z and digits joined by the separator, with nothing before, after or doubled. spring-launch passes the defaults; Spring Launch and spring--launch do not. A workspace that has never touched the page runs on the defaults: lowercase, hyphen, nothing required, block. The page says so plainly: they are defaults, and they are in force.

​
Changing it

Owners and admins see Edit the convention; everyone else sees the rules and can change none. The editor changes what the next link has to look like. Links already created keep the values baked into them; the audit is what finds the ones that no longer comply. If a colleague saves the convention while you have the editor open, your save is refused and you are asked to reload and apply your change again, rather than silently overwriting theirs.
The convention also shapes derived values. A campaign called “Spring Launch” contributes utm_campaign=spring-launch under the defaults and SPRING_LAUNCH under uppercase with underscores. See Campaigns.
In block mode the link is not created. The refusal names the parameter, the value and the rule it broke, in one sentence you can act on:
  • A value in the wrong shape: utm_source ‘Newsletter’ does not match this workspace’s UTM convention (lowercase, letters and digits joined by ’-’).
  • A required parameter left out: utm_medium is required by this workspace’s UTM convention and was not provided.
  • A value outside the approved list, or one a dependency rule forbids: the sentence lists what is allowed instead. See Approved values and Dependency rules.
In warn mode the link is created and the same sentence travels with it: the assistant relays it in the conversation, and the API returns it beside the link. Warn is not off; it is the mode for a workspace adopting rules over links it already has. One check runs on top of your own rules. A value that follows the convention but that Google Analytics would file under the wrong channel — utm_medium=newsletter, which lands in Unassigned instead of Email — is reported with that consequence and the spellings that work, and is refused in block mode like any other violation.
Approving a value or recording a dependency rule must itself respect the format: Facebook cannot be approved under a lowercase convention.

​
From the API and the MCP

GET /api/v1/rules/convention reads the four settings and PUT /api/v1/rules/convention changes them; the body is partial by design, so a rule you do not name is left alone. Reads need rules:read, writes rules:write. The MCP tools are get_convention and set_convention; set_convention, like every rules write, also requires the token holder to be an owner or admin, so a member’s token is refused for its role even when it carries the permission.