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.
Instrucciones 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.
- Alcance
utm_builder:read- Permiso
- Ver el módulo
- Tool del MCP
utm_builder_urls_buildEn la superficie completa; en la compacta,mb_execute_operationconid: "utm_builder.urls.build".
Costo declarado: hasta 0 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
urlstringcuerpoDestination URL, e.g. https://example.com/landing. Without a scheme, https:// is added; only http and https are accepted.
sourcestringcuerpoutm_source (required): where the traffic comes from, e.g. google, facebook, newsletter.
mediumstringcuerpoutm_medium (required): the marketing medium, e.g. cpc, email, social.
campaignstringcuerpoopcionalutm_campaign: the campaign name, e.g. spring_sale_2026.
campaign_idstringcuerpoopcionalutm_id: the campaign id, e.g. abc123.
termstringcuerpoopcionalutm_term: the paid search keyword, e.g. running shoes.
contentstringcuerpoopcionalutm_content: what tells apart links to the same destination, e.g. banner_a, textlink.
Respuesta
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
Errores
Ejemplo
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"
}'Probar con tu API key de prueba
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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"
}'