MB SuiteMB Suite
Menu

API reference · UTM Builder

URLs

utm_builder · urls · 2 operations

POST/v1/utm-builder/urls/buildPOST/v1/utm-builder/urls/bulk-build
POST/v1/utm-builder/urls/build

Build a URL with UTM parameters

utm_builder.urls.build

ReadIdempotentSince 2026-11-01

Adds UTM campaign parameters to a destination URL and returns the tagged URL, exactly as the UTM Builder screen builds it. Nothing is stored or sent anywhere: it is a pure computation with no reads (the screen's history of copied URLs lives in each user's browser and is not available here). url is the destination: https:// is added when the scheme is missing (example.com/landing becomes https://example.com/landing) and only http and https are accepted. source (utm_source) and medium (utm_medium) are required; campaign (utm_campaign), campaign_id (utm_id), term (utm_term) and content (utm_content) are optional. Values are trimmed and kept as sent (analytics tools treat them as case-sensitive), then percent-encoded, with spaces as +. The destination keeps its own query parameters (re-encoded as form data, so %20 becomes +) and its #fragment; the six standard UTM parameters it may already carry are removed first, so only the values sent here remain (replaced_params names them; other utm_* parameters such as utm_source_platform stay). Returns url (the tagged URL, ready to share), utm_params (the UTM parameters applied, by their name in the URL) and replaced_params. For several links to the same destination in one call, use utm_builder.urls.bulk_build. Errors: 400 utm_url_invalid when url is not an http(s) address (details.reason: empty, unsupported_scheme or malformed); 400 invalid_input when source or medium is missing or blank, or a value is longer than 200 characters or has line breaks. Requires view access to UTM Builder.

Instructions for agents

Give the user url exactly as returned: it is already encoded, do not rebuild or re-encode it. If replaced_params is not empty, say that the destination already had those UTM parameters and they were replaced. Keep the naming consistent across links (lowercase, words joined with _ or -): analytics reports count facebook and Facebook as two different sources.

Scope
utm_builder:read
Permission
View the module
MCP tool
utm_builder_urls_buildOn the full surface; on the compact one, mb_execute_operation with id: "utm_builder.urls.build".

Declared cost: up to 0 reads and 0 writes per call (they count against the daily quota).

Parameters

urlstringbodyrequired

Destination URL, e.g. https://example.com/landing. Without a scheme, https:// is added; only http and https are accepted.

sourcestringbodyrequired

utm_source (required): where the traffic comes from, e.g. google, facebook, newsletter.

mediumstringbodyrequired

utm_medium (required): the marketing medium, e.g. cpc, email, social.

campaignstringbodyoptional

utm_campaign: the campaign name, e.g. spring_sale_2026.

campaign_idstringbodyoptional

utm_id: the campaign id, e.g. abc123.

termstringbodyoptional

utm_term: the paid search keyword, e.g. running shoes.

contentstringbodyoptional

utm_content: what tells apart links to the same destination, e.g. banner_a, textlink.

Response

urlstring

The tagged URL, ready to share.

utm_paramsobject

The UTM parameters applied, by their name in the URL (only those with a value).

replaced_paramsarray<enum>

Standard UTM parameters the destination URL already carried: they were removed before applying the new ones.

Values: utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content

Errors

invalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/utm-builder/urls/build" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "source": "SOURCE",
  "medium": "MEDIUM"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/utm-builder/urls/build" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "source": "SOURCE",
  "medium": "MEDIUM"
}'
POST/v1/utm-builder/urls/bulk-build

Build several UTM links for one destination

utm_builder.urls.bulk_build

ReadIdempotentSince 2026-11-01

Builds up to 50 UTM-tagged links to the same destination in one call, like the bulk tab of the UTM Builder screen: url and campaign (utm_campaign, optional) are shared by every link, and each item of variations gives one link with its own source (utm_source), medium (utm_medium) and optional content (utm_content). Each link is exactly what utm_builder.urls.build returns for the same values (same handling of url, encoding and replacement of the UTM parameters the destination already carries). Nothing is stored or sent: a pure computation with no reads. Returns links, in the order of variations, each with source, medium, content (null when not sent) and url, plus replaced_params (the standard UTM parameters the destination already had, removed from every link). Every variation needs source and medium: unlike the screen, an incomplete row is an error (400 invalid_input naming it, e.g. variations.2.medium), never skipped. There is no campaign_id or term here: build those links one by one with utm_builder.urls.build. Errors: 400 utm_url_invalid when url is not an http(s) address; 400 invalid_input for an incomplete variation, an empty list or more than 50 variations, or a value longer than 200 characters. Requires view access to UTM Builder.

Instructions for agents

List the links in the order returned, each with its source and medium, and give every url exactly as returned (already encoded). If replaced_params is not empty, say that the destination already had those UTM parameters and they were replaced in every link.

Scope
utm_builder:read
Permission
View the module
MCP tool
utm_builder_urls_bulk_buildOn the full surface; on the compact one, mb_execute_operation with id: "utm_builder.urls.bulk_build".

Declared cost: up to 0 reads and 0 writes per call (they count against the daily quota).

Parameters

urlstringbodyrequired

Destination URL shared by every link, e.g. https://example.com/landing. Without a scheme, https:// is added; only http and https are accepted.

variationsarray<object>bodyrequired

One link per variation, in this order (1 to 50): source and medium required, content optional.

campaignstringbodyoptional

utm_campaign shared by every link, e.g. spring_sale_2026.

Response

linksarray<object>

One link per variation, in the order sent.

replaced_paramsarray<enum>

Standard UTM parameters the destination URL already carried: they were removed before applying the new ones.

Values: utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content

Errors

invalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/utm-builder/urls/bulk-build" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "variations": []
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/utm-builder/urls/bulk-build" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "variations": []
}'