Build a URL with UTM parameters
utm_builder.urls.build
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.
Instruções para agentes
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.
- Escopo
utm_builder:read- Permissão
- Ver o módulo
- Tool do MCP
utm_builder_urls_buildNa superfície completa; na compacta,mb_execute_operationcomid: "utm_builder.urls.build".
Custo declarado: até 0 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
urlstringcorpoDestination URL, e.g. https://example.com/landing. Without a scheme, https:// is added; only http and https are accepted.
sourcestringcorpoutm_source (required): where the traffic comes from, e.g. google, facebook, newsletter.
mediumstringcorpoutm_medium (required): the marketing medium, e.g. cpc, email, social.
campaignstringcorpoopcionalutm_campaign: the campaign name, e.g. spring_sale_2026.
campaign_idstringcorpoopcionalutm_id: the campaign id, e.g. abc123.
termstringcorpoopcionalutm_term: the paid search keyword, e.g. running shoes.
contentstringcorpoopcionalutm_content: what tells apart links to the same destination, e.g. banner_a, textlink.
Resposta
urlstringThe tagged URL, ready to share.
utm_paramsobjectThe 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.
Valores: utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content
Erros
Exemplo
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"
}'Testar com a sua API key de teste
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.
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"
}'