Tracking Links tracking_links
A campaign's tracked links and their UTM parameters. tracking-links-list with campaign_id lists the links its emails use: domainName is the full destination URL, UTM tags (utm_source=...) included, and textValue the text the email shows; the copy places a link as {{tracking_link:ID}}. Add or change a link's UTM tags: tracking-links-update with changes {domainName: the URL with them}. The email copy itself is email_sequences get. video-* are campaign videos.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through tracking_links_read and changes through tracking_links_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: video-variables-create, tracking-links-create, video-variables-delete, tracking-links-delete, video-lookahead-get, video-settings-get, tracking-links-get, video-variables-list, tracking-links-list, video-settings-replace, video-variables-update, tracking-links-update
video-variables-create
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/video-variables
Path: campaignId
Body (json): key string, library object, video string
Add a shared video to a campaign as a {{key}} variable.
POST /api/v1/campaigns/{campaignId}/video-variables. Needs the campaigns page (edit). Sends Ken-Version 1.1.
key is used as {{key}} in a step (normalized to snake_case). Pass exactly one of video (a share link or embed
code from Loom, YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen) or library_connection_id with
provider_video_id (a video from sending_providers(operation="video-provider-connections-list-library"), HeyGen
only). The variable starts pending. 400 validation_failed detail invalid_key, reserved_key, key_in_use (a custom
variable has it), too_many_variables (20), video_required, unsupported_video, invalid_video, video_too_large,
connection_unavailable or library_not_supported; 409 variable_exists. Early access: 404 not_found until the
workspace has the campaign_videos flag, and 403 detail feature_disabled for a provider that is off. Returns 201
with the variable (fields of video-variables-list).
tracking-links-create
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/tracking-links
Path: campaignId
Body (json): domainName string, name string, textValue string
Create a tracking link on a campaign. Public. Requires Delivery edit. Returns the created link.
POST /api/v1/campaigns/{campaignId}/tracking-links. Public. Sends Ken-Version 1.1.
Requires Delivery edit. The API returns 201. name is required and at most 1024
characters. domainName stays the destination and must be an http or https URL.
textValue is optional display text. A campaign outside the workspace is
not_found before the create.
video-variables-delete
Write. DELETE https://api.ken.so/v1/campaigns/{campaignId}/video-variables/{variableKey}
Path: campaignId, variableKey
Delete one campaign video variable.
DELETE /api/v1/campaigns/{campaignId}/video-variables/{variableKey}. Needs the campaigns page (edit). Sends
Ken-Version 1.1. Answers 204. 404 for an unknown key; 409 video_in_use while a sent or queued step uses the video.
Early access: 404 not_found until the workspace has the campaign_videos flag.
tracking-links-delete
Write. DELETE https://api.ken.so/v1/tracking-links/{trackingLinkId}
Path: trackingLinkId
Delete a tracking link. Public. Requires Delivery edit access (owners, admins and editors by default). Returns 204.
DELETE /api/v1/tracking-links/{trackingLinkId}. Public. Sends Ken-Version 1.1.
Requires Delivery edit access (owners, admins and editors by default). Returns 204. A link outside the workspace is not_found
before the delete. A link whose campaign is still generating tracking links
is conflict.
video-lookahead-get
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/video-lookahead
Path: campaignId
Count the campaign's leads that would get a generated video now.
GET /api/v1/campaigns/{campaignId}/video-lookahead. Needs the campaigns page (view). Sends Ken-Version 1.1.
Returns {campaignId, leadsDue (leads whose next step that uses {{custom_video}} is due within lookaheadHours and
that have no video yet, at most 50,000), lookaheadHours, computedAt}, computed like the generation job. The
campaign's sending state is not checked. 404 for a campaign outside the workspace. Early access: 404 not_found
until the workspace has the campaign_videos flag.
video-settings-get
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/video-settings
Path: campaignId
Read a campaign's video settings: which connection and source make its per-lead videos.
GET /api/v1/campaigns/{campaignId}/video-settings. Needs the campaigns page (view). Sends Ken-Version 1.1.
Returns {campaignId, source {connectionId, provider (null when the connection is gone), reference (the Sendspark
dynamic campaign id, HeyGen template id or Vidyard campaign id), leadOwnerEmail (Vidyard)}, variableMapping
(provider variable name to one Kenso token like {{first_name}}), thumbnailImageVariableKey, videoRequired (null:
a step needs the video when the campaign has a source), generationEnabled, updatedAt}. A campaign that never
saved any answers the defaults (source null, empty mapping, generationEnabled false, updatedAt null). 404 when the
campaign is not in the workspace. Early access: 404 not_found until the workspace has the campaign_videos flag.
tracking-links-get
Read. GET https://api.ken.so/v1/tracking-links/{trackingLinkId}
Path: trackingLinkId
Return one tracking link. Public. A link outside the workspace is not_found.
GET /api/v1/tracking-links/{trackingLinkId}. Public. Sends Ken-Version 1.1.
Requires Delivery view. Fields stay name, domainName, and textValue.
textValue is omitted when blank. A link outside the workspace is not_found.
video-variables-list
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/video-variables
Path: campaignId
List a campaign's video variables: shared videos every lead on a step gets as {{key}}.
GET /api/v1/campaigns/{campaignId}/video-variables. Needs the campaigns page (view). Sends Ken-Version 1.1. Every
live video variable of the campaign by key, at most 20, so one page: each {key, status (pending until the
thumbnail is ready, ready, failed), source (paste, library), provider (loom, youtube, vimeo, wistia, vidyard,
sendspark, heygen), watchUrl, embedUrl, error {code, detail}, createdAt, updatedAt}. 404 for a campaign outside
the workspace. Early access: 404 not_found until the workspace has the campaign_videos flag.
tracking-links-list
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/tracking-links
Path: campaignId
Query: cursor string, limit integer
List the links in a campaign's emails, with their UTM parameters. Each link has name, domainName (the full destination URL, UTM tags such as utm_source included) and textValue (the text the email shows).
GET /api/v1/campaigns/{campaignId}/tracking-links. Public. Sends Ken-Version 1.1.
The copy places a link as {{tracking_link:ID}}. To add or change UTM tags,
update the link's domainName with tracking-links-update.
Requires Delivery view. Pages are ordered by id. limit is 1 to 200. Omit it
for the server default. There is no totalCount.
Fields stay name, domainName, and textValue. textValue is omitted when blank.
A campaign outside the workspace is not_found before the list is read.
The workspace-wide GET /v1/redirect-links?clientId= list stays legacy.
video-settings-replace
Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/video-settings
Path: campaignId
Body (json): generationEnabled boolean, source object, thumbnailImageVariableKey string, variableMapping object, videoRequired boolean
Replace a campaign's video settings. Omitted fields reset to their defaults.
PUT /api/v1/campaigns/{campaignId}/video-settings. Needs the campaigns page (edit). Sends Ken-Version 1.1.
Replaces the whole settings, so read them with tracking_links(operation="video-settings-get") first and pass
everything to keep. The source is connection_id (a live connection from
sending_providers(operation="video-provider-connections-list")) with reference (an id from
sending_providers(operation="video-provider-connections-list-sources"), 1 to 200 characters), plus
lead_owner_email for Vidyard (required there, ignored elsewhere); omit both to clear it. variable_mapping maps
each provider variable name (1 to 100 characters, at most 50) to exactly one Kenso token, like
{"first_name": "{{first_name}}"}. thumbnail_image_variable_key names the image variable used as the thumbnail.
video_required: whether a step waits for the lead's video (null default: when the campaign has a source).
generation_enabled: whether Kenso generates the videos; needs a source. No provider call happens here.
400 validation_failed detail connection_not_found, invalid_reference, invalid_lead_owner_email,
invalid_variable_mapping, invalid_thumbnail_variable_key or source_required; 404 when the campaign is not in the
workspace. Early access: 404 not_found until the workspace has the campaign_videos flag, and 403 detail
feature_disabled while the source provider's own flag is off. Nothing is stored on a failure. Returns the
settings (fields of video-settings-get).
video-variables-update
Write. PATCH https://api.ken.so/v1/campaigns/{campaignId}/video-variables/{variableKey}
Path: campaignId, variableKey
Body (json): library object, video string
Replace the video behind one campaign video variable.
PATCH /api/v1/campaigns/{campaignId}/video-variables/{variableKey}. Needs the campaigns page (edit). Sends
Ken-Version 1.1. Exactly one of video or library_connection_id with provider_video_id, as in video-variables-create.
The key never changes; the variable goes back to pending. 400 validation_failed detail video_required,
unsupported_video, invalid_video, video_too_large, connection_unavailable or library_not_supported; 404 for an
unknown key; 409 video_in_use while a sent or queued step uses the video. Early access: 404 not_found until the
workspace has the campaign_videos flag, and 403 detail feature_disabled for a provider that is off.
tracking-links-update
Write. PATCH https://api.ken.so/v1/tracking-links/{trackingLinkId}
Path: trackingLinkId
Body (json): domainName string, name string, textValue string
Update a tracking link. Absent fields stay unchanged. JSON null clears textValue. Public. Requires Delivery edit.
PATCH /api/v1/tracking-links/{trackingLinkId}. Public. Sends Ken-Version 1.1.
Requires Delivery edit. Fields stay name, domainName, and textValue.
Absent fields stay unchanged. JSON null clears textValue. name and
domainName cannot be null. A link outside the workspace is not_found
before the write. A link whose campaign is still generating tracking
links is conflict. When Kenso enforces its link abuse gate (DEV-3690), a
domainName change on a link served from Kenso's shared tracking host is 409
shared_host_link_frozen (create a new tracking link instead), and a
domainName change off a paid plan is 402 plan_limit_reached with
error.refusal.code link_edit_requires_paid_plan. name and textValue edits
are never refused.