{
"openapi": "3.1.0",
"info": {
"title": "utm.new URL Builder API",
"version": "2026-08-24",
"description": "Generate campaign-tagged URLs using the recommended UTM template for each advertising platform, and get back structured warnings about mistakes specific to that platform — duplicated click IDs, macros the platform cannot substitute, URLs past its length limit.\n\nFree, no authentication, no rate limit. CORS is open.",
"contact": {
"url": "https://utm.new/contact"
},
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/"
}
},
"servers": [
{
"url": "https://utm.new"
}
],
"paths": {
"/api/v1/build": {
"get": {
"operationId": "buildTaggedUrl",
"summary": "Build one tagged URL",
"description": "Applies a platform's recommended UTM template to a destination URL. Deterministic and cacheable. Use override. to change a template value (empty string removes it) and extra. for non-UTM params.",
"parameters": [
{
"name": "url",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Destination URL. Must be http or https.",
"example": "https://example.com/pricing"
},
{
"name": "platform",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"blank",
"chatgpt-ads",
"facebook-bio",
"google-ads",
"instagram-bio",
"linkedin-ads",
"linkedin-bio",
"mediago",
"meta-ads",
"mgid",
"microsoft-ads",
"newsletter",
"organic-social",
"outbrain",
"partner",
"pinterest-ads",
"pinterest-bio",
"qr-code",
"quora-ads",
"reddit-ads",
"revcontent",
"snapchat-ads",
"spotify-ads",
"taboola",
"threads-bio",
"tiktok-ads",
"tiktok-bio",
"x-ads",
"x-bio",
"youtube-ads",
"youtube-bio"
]
},
"description": "Platform id. GET /api/v1/platforms.json for the full list.",
"example": "google-ads"
},
{
"name": "override.utm_campaign",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Replace a template value. Any override. is accepted; set to an empty string to omit that parameter entirely."
},
{
"name": "extra.ref",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Append a non-UTM parameter. Any extra. is accepted. Passing a utm_* key here returns a reserved_param_in_extra warning."
}
],
"responses": {
"200": {
"description": "The tagged URL and any warnings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The tagged URL."
},
"platform": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"published",
"draft",
"needs-update"
]
},
"docs": {
"type": [
"string",
"null"
],
"description": "Reference page for the platform, or null when status is not \"published\" — those platforms are catalog-only and have no page."
}
}
},
"params": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "The parameters that were applied, in canonical order."
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable identifier for the condition. Safe to branch on.",
"enum": [
"click_id_auto_tagged",
"click_id_missing",
"tokens_unsupported",
"utm_id_unsupported",
"url_length_exceeded",
"params_replaced",
"platform_unverified",
"platform_is_receiver",
"reserved_param_in_extra",
"override_not_in_template"
]
},
"severity": {
"type": "string",
"enum": [
"warning",
"info"
]
},
"message": {
"type": "string"
},
"param": {
"type": "string"
}
},
"required": [
"code",
"severity",
"message"
]
},
"description": "Problems the catalog knows about for this platform. An empty array means the link is clean. Always surface these to the user."
}
},
"required": [
"url",
"platform",
"params",
"warnings"
]
}
}
}
},
"400": {
"description": "Missing or invalid url/platform."
},
"404": {
"description": "Unknown platform id."
}
}
},
"post": {
"operationId": "buildTaggedUrls",
"summary": "Build one or many tagged URLs",
"description": "Same as GET, with structured overrides. Send a \"links\" array to build up to 50 URLs in one call; per-link errors are reported inline so one bad entry does not fail the batch.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"title": "Single",
"properties": {
"url": {
"type": "string"
},
"platform": {
"type": "string",
"enum": [
"blank",
"chatgpt-ads",
"facebook-bio",
"google-ads",
"instagram-bio",
"linkedin-ads",
"linkedin-bio",
"mediago",
"meta-ads",
"mgid",
"microsoft-ads",
"newsletter",
"organic-social",
"outbrain",
"partner",
"pinterest-ads",
"pinterest-bio",
"qr-code",
"quora-ads",
"reddit-ads",
"revcontent",
"snapchat-ads",
"spotify-ads",
"taboola",
"threads-bio",
"tiktok-ads",
"tiktok-bio",
"x-ads",
"x-bio",
"youtube-ads",
"youtube-bio"
]
},
"overrides": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"extra": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"url",
"platform"
]
},
{
"type": "object",
"title": "Batch",
"properties": {
"links": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"platform": {
"type": "string"
},
"overrides": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"extra": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"url",
"platform"
]
}
}
},
"required": [
"links"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "One result, or a results array for a batch."
},
"400": {
"description": "Invalid body, empty batch, or batch over 50."
},
"413": {
"description": "Request body too large."
}
}
}
},
"/api/v1/platforms.json": {
"get": {
"operationId": "listPlatforms",
"summary": "List every platform",
"description": "The full catalog: id, category, whether the platform is taggable, and its click-ID rule. Static and CDN-served.",
"responses": {
"200": {
"description": "The platform catalog."
}
}
}
},
"/api/v1/platforms/{id}.json": {
"get": {
"operationId": "getPlatform",
"summary": "Get one platform in full",
"description": "Recommended params, click-ID rule, click-time tokens, and quick facts.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"blank",
"chatgpt",
"chatgpt-ads",
"claude",
"facebook-bio",
"gemini",
"google-ads",
"google-analytics",
"instagram-bio",
"linkedin-ads",
"linkedin-bio",
"mediago",
"meta-ads",
"mgid",
"microsoft-ads",
"microsoft-copilot",
"newsletter",
"organic-social",
"outbrain",
"partner",
"perplexity",
"pinterest-ads",
"pinterest-bio",
"qr-code",
"quora-ads",
"reddit-ads",
"revcontent",
"snapchat-ads",
"spotify-ads",
"taboola",
"threads-bio",
"tiktok-ads",
"tiktok-bio",
"x-ads",
"x-bio",
"youtube-ads",
"youtube-bio"
]
}
}
],
"responses": {
"200": {
"description": "The platform record."
},
"404": {
"description": "Unknown platform id."
}
}
}
}
}
}