Kenso MCP tools

Studio Pages studio_pages

Personalized Studio pages, one per template and account: fill runs, hand edits and natural links. A page's first link publishes it and charges 1 credit.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through studio_pages_read and changes through studio_pages_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: asset-engagement-get, asset-template-delete, asset-template-get, asset-template-put, run-create, create-link, customize, engagement, run-estimate, run-get, get, run-list, list, list-links, prepare, refill, republish, submit, update, update-version

asset-engagement-get

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/asset-engagement

Path: campaignId

Return how a campaign's Studio pages were read: views, companies, people, CTA clicks.

GET /api/v1/campaigns/{campaignId}/asset-engagement. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Counts only views judged human. uniqueCompanies: companies whose
page has a human view. uniquePeople: leads with a human view on their link. ctaClicks
leaves out automated events. companies: one row per company page with activity
(contactsCompanyId, assetId, humanViews, uniquePeople, ctaClicks, lastViewedAt), most
human views first, at most 200.

asset-template-delete

Write. Early access: needs studio on for the workspace. DELETE https://api.ken.so/v1/campaigns/{campaignId}/asset-template

Path: campaignId

Stop using a Studio template in a campaign. Only on the user's explicit request. Steps with {{asset_link}} stop sending until a template is set again.

DELETE /api/v1/campaigns/{campaignId}/asset-template. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Returns 204. Pages already built and their links stay as they are.
404 when the campaign has no Studio template.

asset-template-get

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/asset-template

Path: campaignId

Return the Studio template version a campaign's {{asset_link}} pages are built from. 404 when the campaign has no Studio template.

GET /api/v1/campaigns/{campaignId}/asset-template. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Returns campaignId, templateId, templateVersionId, versionNumber,
templateName, pinnedAt and pinnedBy (kind, memberId, via).

asset-template-put

Write. Early access: needs studio on for the workspace. PUT https://api.ken.so/v1/campaigns/{campaignId}/asset-template

Path: campaignId

Body (json): templateId integer, versionId integer

Set the Studio template a campaign's {{asset_link}} uses: one page per company. Pins the latest published version unless version_id is given. One template per campaign.

PUT /api/v1/campaigns/{campaignId}/asset-template. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. version_id must be a published version of template_id (default:
the latest published one). The same template with another version moves the campaign
to it: pages built from then on use it, existing pages keep theirs. Needs campaigns
and studio edit plus ask: once pinned, the campaign's sends queue Ken's paid page fills.
Errors: 404 when the campaign, template or version is not in the workspace.
409 invalid_state with studio_template_not_published, studio_version_not_published, or
studio_template_without_fallbacks (a required slot has no fallback and the version
ships no fallback.liquid, so the page cannot render before its fill is done).
409 conflict with studio_campaign_has_template when the campaign uses another
template: remove it first with operation asset-template-delete.

run-create

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-runs

Body (json): accountIds array, assetIds array, campaignId integer, contactIds array, executor string, templateId integer, trigger string, versionId integer

Fill a template on up to 500 accounts, existing pages, or leads of a pinned campaign. Estimate first with operation run-estimate. Returns the run (201).

POST /api/v1/asset-runs. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Send exactly one target: account_ids, asset_ids, or campaign_id with contact_ids
(each list at most 500 positive ids).
version_id must be published (default: the latest published version).
executor: ken (default) queues the run for Ken on credits; agent leaves the pages
in draft for prepare and submit. trigger: mcp (default here), ui, touch.
An existing page is reused; a live or building page is left out (skipped), and
only the pages filled are priced, credit-checked and counted against the quota.
Campaign leads: builds the campaign page of each lead's company ahead of a send,
one page per company shared by its leads, on the campaign's pinned version (pin it
with operation asset-template-put first). template_id must be the pinned
template and version_id, when sent, the pinned version (else a validation error
with code pin_mismatch). Each page in assets carries campaignId and
contactsCompanyId. Leads that get no page are in skipped with contactId and a
reason: not_found (not a live lead of the campaign), no_company,
page_other_template or page_not_created. On a recruiting campaign (recruiting
flag on, recruiting template pinned) it builds one page per lead instead: each
page carries contactId, no contactsCompanyId, and no_company never applies.
When no lead gets a page, the run is a validation error listing each lead (field
contactIds[i]). Then check each page's grade (operation run-get) and cut a
contact link on the ones that passed (operation create-link with contact_id).
Errors: 402 when the workspace cannot cover the run. 409 invalid_state with
studio_template_not_published, studio_version_not_published,
studio_campaign_not_pinned (the campaign has no Studio template), or
studio_nothing_to_run (every page was left out; details list each page and why).
409 conflict (concurrent_change): a page changed while the run was priced. Retry.
429 quota_exceeded past studioRunAsset (5,000 pages a day per workspace).

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/links

Path: assetId

Body (json): contactId integer, host string, personId integer, shared boolean

Create a natural link to a page for a person, a campaign contact, or shared. The first link publishes the page and charges 1 credit; later links are free.

POST /api/v1/assets/{assetId}/links. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Send exactly one of person_id (an Accounts person), contact_id
(a lead, on a campaign page) or shared=true. The URL is https://{host}/{account}/{page}
(shared) or .../{page}-for-{first} (person) on the workspace's own link host.
An existing link for the same person, contact or shared slot comes back with 200
(a lead's newest, when it has links on several hosts); a new one with 201.
host (staff only, with contact_id or person_id): cut the link on this host, e.g.
link.example.com, a ready link host of the workspace with a proven serving proof,
instead of the page's host. The lead's links on other hosts keep serving. A person
holds one link per page, so their old link is retired and its URL stops serving.
The same host again returns that link. 400 host_unavailable when the host is not
one; 403 for a caller who is not staff.
Errors: 402 insufficient credits on the first link (nothing is created).
409 invalid_state with studio_no_host (set up link tracking on a sending domain),
studio_page_not_ready (not filled and the template has no fallback, or the page
needs review; wait for the fill, refill, or prepare and submit),
studio_page_retired (republish it first), studio_template_deleted (its template
was deleted while the link was being created; build the page on another template).
429 quota_exceeded past studioLinkCreate (2,000 links a day per workspace).

customize

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/customize

Path: assetId

Body (json): expected string, kenOverrides any JSON, layout object, markReviewed boolean, overrides any JSON, reset boolean, resetKenOverrides boolean, resetLayout boolean

Hand-edit one page: its slots (overrides), its own layout, its Ken values, or reset them. Read the page with get include_source=true first and send its source.token as expected.

POST /api/v1/assets/{assetId}/customize. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Send at least one of overrides, layout, ken_overrides,
reset=true, reset_layout=true or reset_ken_overrides=true; they combine in one save.
overrides: {slot: value}, merged into the page's overrides; a null value removes
that slot's override.
layout: this page's own copy of the template, {"template": "<the whole
template.liquid>", "sections": [{"id": "hero", "label": "Hero"}], "files":
{"<path from upload-urls>": {"uploadId": "..."}}}. template is required and sent as
given. sections (optional) is the page's sections list: send it when you add, remove
or reorder data-section elements; omit it to keep the current list. files (optional)
adds images uploaded with studio_docs(operation="create-upload-url"), each under the
path that call returned (assets/<name>-<12 hex>.<ext>; the template shows it as
{{ asset_url | append: '/<name>-<12 hex>.<ext>' }}). Or fetch a public https image
instead of uploading it: {"assets/hero.png": {"fromUrl": "https://..."}}. Kenso fetches
it (png, jpg, gif, webp or avif, at most 5 MB each, 20 fromUrl images and 30 seconds
a save) and stores it under a new name, assets/hero-<12 hex>.png. Write the template
with the name you asked for ({{ asset_url }}/hero.png or {{ asset_url | append:
'/hero.png' }}): the same save rewrites each such reference to the stored name, and
the answer's data.layout.renamed maps each requested path to its stored one
({"assets/hero.png": "assets/hero-<12 hex>.png"}). Only a reference after the '/'
that follows {{ asset_url }}, after append: '/, or after a quote, and ending at a
quote, ')', '?', '#', ',', '>' or a space, is rewritten; a URL on another host is
left alone. A null value removes an image already on the page from its
list. A page holds at most 50 images. The template and every other page stay as they
are. The copy runs through the template validator: errors come back as
validation_failed with file:line and the rule.
ken_overrides: what account.*, sender.* and brand.* show on this page only:
{"account": {"name", "domain", "industry", "size_band"}, "sender": {"name",
"first_name", "last_name", "title"}, "brand": {"logo_url", "name",
"colors": {primary, secondary, accent, background, text}, "fonts": {heading,
body}}}. brand.name sets the name templates show (product_name is accepted and
does the same). Strings up to 500 characters; logo_url an https URL; colors #rgb or
#rrggbb. logo_url must be an image the page may load: an https URL under
https://api.ken.so/media/ (the page's Content Security Policy blocks other hosts).
No string may hold a NUL character or an unpaired UTF-16 surrogate.
A null value removes one; a null group ({"brand": null}) drops that group.
person.* stays per link; sender.signature_html cannot be overridden.
reset=true drops overrides, the layout and Ken overrides, and stands alone.
reset_layout=true drops the page's layout (not with layout).
reset_ken_overrides=true drops its Ken overrides (not with ken_overrides).
expected: source.token (the page's updatedAt) from your last read. 409
concurrent_change when the page changed since: read again and re-apply. Without
expected, the last write wins.
A live page is republished with the edit. A page with its own layout stays on its
version when the template publishes (update-version merges it).
Errors: 400 unknown_slot, link-domain-blocked, a value that breaks its slot schema,
validation_failed for the layout or ken_overrides (invalid_path when a files key is
not the path upload-urls returned, invalid_url, fetch_failed or
fetch_budget_exhausted for a fromUrl image); 409 concurrent_change; 409 invalid_state with
studio_page_busy for a layout save, or a reset of a page with its own layout, while
a fill or update run is working on the page (wait for it with run-get, then read
and save again). overrides and ken_overrides alone save during a run.

engagement

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/assets/{assetId}/engagement

Path: assetId

Return who read one Studio page, for how long, and what they did on it.

GET /api/v1/assets/{assetId}/engagement. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Needs Studio view.
views: human, scanner and pending (not judged yet) view counts. Only human views
count as reads; scanners are mail-security bots that open links before the reader.
people: one row per person or lead link with a human view, most recent first
(personId or contactId, name, firstViewAt, lastViewAt, visits, visibleMs, and
likelyForwarded when a human view on that link came from another network and device).
sections: visible time per section id across human views, longest first.
events: the latest 50 cta_click, pdf_download, form_submit and fresh_copy_request
events (kind, at, personId or contactId, ref = the CTA id, link, PDF or form id).
lastActivityAt, and attribution.meetings: rule cta_or_14d on an account page (meetings
booked on the page's account after a booking CTA click or within 14 days of a human
view), rule page_booking (bookings made from the page) on a candidate's page; null for
a company page in a campaign.

run-estimate

Read. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-runs/estimate

Body (json): accountCount integer, executor string, templateId integer, versionId integer

Estimate what a run over account_count accounts costs. Writes nothing.

POST /api/v1/asset-runs/estimate. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. account_count 1 to 500. version_id default: the latest
published version. executor ken (default) or agent; model tokens are 0 for agent.
Returns millicredits and credits with a per-account breakdown (page link, data
steps, model tokens).

run-get

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-runs/{runId}

Path: runId

Return one run: counts, each page's state and its steps (latest attempt per step).

GET /api/v1/asset-runs/{runId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
state: queued, running, completed, failed, cancelled. costMillicredits is what the
run has charged so far.

get

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/assets/{assetId}

Path: assetId

Return one Studio page with its data, overrides, slot status, template and links. include_source=true adds data.source: the page's template text, sections and save token, to edit it.

GET /api/v1/assets/{assetId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
slotStatus maps each slot to filled, fallback or failed. previewUrl is a signed
private preview of a ready, needs_review or live page, valid 1 to 2 hours;
opening it counts no view. It is null for other states and when the workspace
has no Studio host.
layout is the page's own copy of the template (template, sections, baseVersionId,
assets), or null while it follows its version. layoutConflict names the version
whose merge conflicted. kenOverrides are this page's Ken-value overrides;
kenValues what account, sender and brand show before them.
include_source=true adds data.source in the same call: {"template": the page's
template.liquid (its own layout, else its pinned version's), "sections": its
sections list as [{id, label}] (null when unreadable), "versionId": the pinned
version, "own": true when the page has its own layout, "token": the page's
updatedAt}. Edit template and save it with customize layout={"template": ...} and
expected=token.

run-list

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-runs

Query: cursor string, limit integer, state string, templateId integer

List Studio fill runs, newest first, by template or state.

GET /api/v1/asset-runs. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
state (comma = OR): queued, running, completed, failed, cancelled. limit 1 to 200.
Pass pagination.nextCursor back unchanged as cursor.

list

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/assets

Query: accountId integer, campaignId integer, cursor string, limit integer, state string, templateId integer

List Studio pages, newest first, by template, account, campaign or state. Items leave out data and overrides; get one page for them.

GET /api/v1/assets. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
state (comma = OR): draft, building, ready, needs_review, failed, live, retired.
limit 1 to 200. Pass pagination.nextCursor back unchanged as cursor.

Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/assets/{assetId}/links

Path: assetId

Query: cursor string, limit integer

List a page's links, oldest first: URL, person or shared, and when the edge published it.

GET /api/v1/assets/{assetId}/links. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. limit 1 to 200. Pass pagination.nextCursor back unchanged.
publishedAt is null while the edge publish is pending; create the link again to
retry it.

prepare

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/prepare

Path: assetId

Body (json): data any JSON

Get the recipe to fill a page with your own model: Ken runs the data steps. Write the slots from the returned prompt and grade steps, then submit.

POST /api/v1/assets/{assetId}/prepare. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. For pages of a run created with executor agent.
data: optional, the slots written so far. While the recipe lists deferred steps
(they wait for a slot an earlier agent step writes), call prepare again with data.
Needs the Ask permission. Before Ken runs a paid step it checks the balance (402
insufficient credits), your monthly credit limit (402 member_credit_limit_reached)
and takes one unit of the daily studioRunAsset quota (429); a prepare that only
reuses recorded steps takes none. Returns 503 while Studio fills are unavailable.

refill

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/refill

Path: assetId

Refill one page on its pinned version with Ken's executor. Returns the run (201). A live page stays live and keeps its links. A page that follows the latest version and is not live or retired refills on the latest published version.

POST /api/v1/assets/{assetId}/refill. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. No body. Follow the run with operation run-get.
409 invalid_state with studio_page_building while a fill runs. 429 quota_exceeded
past studioRunAsset (5,000 pages a day per workspace).

republish

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/republish

Path: assetId

Put a retired page back live on the same URLs. Charges 1 page credit again.

POST /api/v1/assets/{assetId}/republish. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. No body. A live page only gets its edge copy refreshed, with no
charge. 402 when the workspace cannot cover the credit. 409 invalid_state with
studio_page_not_retired (draft or ready page: create a link to publish it),
studio_page_building, studio_page_no_links (its account or links were removed), or
studio_page_not_ready (a refill left it unfilled with no template fallback, or it
needs review; refill, or prepare and submit), or studio_template_deleted (its
template was deleted; build a new page on another template). A refusal charges
nothing.

submit

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/submit

Path: assetId

Body (json): data any JSON, gradeResults any JSON, versionId integer

Submit the data you filled after prepare. Kenso validates it against the slot schema.

POST /api/v1/assets/{assetId}/submit. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. data: the filled data object. grade_results: optional list
with one entry per grade step you ran, [{"stepId": "check", "score": 8, "pass": true,
"reasons": "..."}]; a pass false marks the page needs_review. version_id: the
recipe's versionId from prepare; send it. When the page fills another template
version by now (a publish or another run moved it), the submit changes nothing and
returns 409 invalid_state with studio_version_changed: prepare again, write the
slots it returns, and submit with its versionId. Returns the page
(state, slotStatus) with issues: every finding on the submitted data, each
{path, rule, severity, message, fix}. A slot with an error renders its fallback;
fix that slot and submit again. Data refused outright raises a validation error
whose details carry the same findings (field is the slot path, code the rule id).
A grade step's checks (the instruction's checks block) run on its graded slots:
a hit raises a validation error with code studio.grade_checks per phrase and saves
nothing, unless grade_results reports that grade with pass false, which sends the
page to needs_review. Rewrite the quoted phrases and submit again.
Returns 503 while Studio fills are unavailable.

update

Write. Early access: needs studio on for the workspace. PATCH https://api.ken.so/v1/assets/{assetId}

Path: assetId

Body (json): pageSlug string

Change a page's slug, the {page} part of its link URLs. Only before its first link.

PATCH /api/v1/assets/{assetId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
page_slug: lowercase letters, digits and single hyphens, at most 60 characters.
The first link freezes the slug: 409 invalid_state with studio_slug_frozen.

update-version

Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/update-version

Path: assetId

Body (json): layout string, versionId integer

Move one page to a newer published version of its template. Returns the run (201). version_id defaults to the latest published version. A live page stays live on its links.

POST /api/v1/assets/{assetId}/update-version. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. version_id: a published version of the page's template, newer
than the page's pin (default: the latest published). A live page gets an update_live
run that refills only the steps that changed and republishes it; a draft or ready
page refills on the version. Follow the run with operation run-get.
409 invalid_state with already_on_version, older_version, no_published_version,
version_not_published, page_retired (republish it first) or studio_page_building.
402 when the workspace cannot cover the run. 429 quota_exceeded past studioRunAsset.
A page with its own layout dry-runs the merge of the new version into its copy
first. When it merges, the run is queued like any other page and its layoutMerge
says what the dry run found: "clean" (the page keeps a layout of its own on the new
version) or "identical" (the merged copy equals the new version, so the page drops
its copy and follows the version). The run merges again when it finishes and can
still flag a conflict if the page changed meanwhile: once the run is done, read the
page with operation get and check layoutConflict. 409 conflict with layout_conflict
means nothing moved and the page is flagged (layoutConflict on get); each error
detail is one clash ("Lines 12-14: this page has ..., v4 has ..."). Ask the user,
then call again with layout="keep" or "take".
layout: answers a layout_conflict. keep leaves the page where it is, with or
without its own layout: the API answers 204 and this returns {"kept": true,
"assetId": <id>}. No run is queued, nothing is charged and the conflict flag
clears. keep on a building page is 409 studio_page_building like any other call:
a run may be moving it, so wait for the run, read the page, then answer again.
take drops the page's layout and moves to the new version, keeping its
slot overrides: returns the run (layoutMerge null). On a page without its own
layout, take moves it as usual.