Studio Templates studio_templates
Kenso Studio templates: reusable landing page and doc designs built from a bundle of files. Pull, edit and push the draft, validate, then publish a version. preview's sample is a bundle path such as samples/<name>.json. template_type is what it is for (reverse_demo, landing_page, audit, report, ...); template_format is page, doc or email.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through studio_templates_read and changes through studio_templates_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: datasets-create, create, create-upload-url, datasets-delete, delete, duplicate, get, get-version, get-webhook-secret, datasets-list, list, starters-list, list-versions, preview, publish, pull, push, restore-version, update, validate
datasets-create
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/datasets
Path: templateId
Body (json): name string, uploadId string
Add a CSV dataset to a Studio template from an upload. Returns 201 with the dataset. Upload the CSV first with create-upload-url. Header row first, 5 MB and 50,000 rows max.
POST /api/v1/asset-templates/{templateId}/datasets. Staff. Sends Ken-Version 1.1.
Requires Studio edit.
name: the name the recipe's dataset step uses, 1 to 100 characters. upload_id:
the uploadId from create-upload-url, after the PUT. The CSV needs a header row
and holds at most 5 MB and 50,000 rows.
create
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates
Body (json): description string, format string, name string, slug string, starterSlug string, type string
Create a Studio template, empty or copied from a starter. Returns 201 with the template. name is required unless starter_slug is set (starters-list); the starter's files become draft v1.
POST /api/v1/asset-templates. Staff. Sends Ken-Version 1.1. Requires Studio edit.
name: 1 to 200 characters. template_type: reverse_demo, landing_page, audit,
report, event, calculator, recruiting, other (required unless starter_slug is
set; recruiting needs the workspace's recruiting flag, else 400
feature_disabled). template_format: page (default), doc or email (email needs the
workspace's studio_email feature, else 400 feature_disabled; an email bundle sets
format "email" and a subject in studio.json, has no sections, and is checked by the
email rules: inline CSS only, no scripts, forms or kit tags, https images, an
{{ unsubscribe_link }}, 100 KB at most, the shared Liquid filter list). slug: the default
page slug, lowercase letters, digits and single hyphens, up to 60; defaults
from the name.
starter_slug: a slug from starters-list. The starter's name, type and format are
the defaults, and its bundle becomes draft version 1. Then pull, edit, push,
validate and publish.
create-upload-url
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/upload-urls
Path: templateId
Body (json): bytes integer, contentType string, path string
Get a presigned URL to upload one binary file (5 MB max) for a push or a dataset. PUT the file to url with exactly the returned headers within 15 minutes, then use uploadId.
POST /api/v1/asset-templates/{templateId}/upload-urls. Staff. Sends Ken-Version 1.1.
Requires Studio edit.
path: the bundle path the file is for (assets/logo.png), or the CSV name for a
dataset. content_type: the MIME type the PUT sends. size_bytes: the exact file
size, up to 5 MB. The url is signed for exactly that many bytes: a body of any
other size is refused, so request a new url if the file changes.
Returns url, headers and uploadId. PUT the bytes to url with exactly those
headers within 15 minutes. Then send {"uploadId": ...} as a file in push, or
upload_id in datasets-create.
datasets-delete
Write. Early access: needs studio on for the workspace. DELETE https://api.ken.so/v1/asset-template-datasets/{datasetId}
Path: datasetId
Delete a Studio template dataset. Only on the user's explicit request. Requires Studio edit access.
DELETE /api/v1/asset-template-datasets/{datasetId}. Staff. Sends Ken-Version 1.1.
Returns 204. dataset_id is id from datasets-list.
delete
Write. Early access: needs studio on for the workspace. DELETE https://api.ken.so/v1/asset-templates/{templateId}
Path: templateId
Query: force boolean (required)
Delete a Studio template. Only on the user's explicit request. Requires Studio edit access. A template with live pages fails with template_has_live_pages unless force=true.
DELETE /api/v1/asset-templates/{templateId}. Staff. Sends Ken-Version 1.1.
Returns 204. 409 invalid_state (template_has_live_pages) while pages built from it
are live. force=true retires those pages first: ask the user before sending it.
force takes each live page off the edge first and deletes the template only when
every one is retired; otherwise 409 invalid_state (pages_not_retired) names how
many are still live and nothing is deleted. Retry the delete.
duplicate
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/duplicate
Path: templateId
Body (json): name string
Copy a Studio template into a new one. Returns 201 with the new template. Draft v1 of the copy holds the source's latest published files (else its draft) and its datasets.
POST /api/v1/asset-templates/{templateId}/duplicate. Staff. Sends Ken-Version 1.1.
Requires Studio edit. name: 1 to 200 characters, default "{source name} copy". The
copy keeps the source's type, format, description and starter, takes its slug from
the name, and gets draft version 1 with the files of the source's latest published
version (else its draft) plus a copy of every dataset. Pages and links are not
copied. 404 when the template is not in this workspace. 409 invalid_state with
nothing_to_copy when the source has no version with files yet: push to it first.
get
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}
Path: templateId
Return one Studio template with its usage counts.
GET /api/v1/asset-templates/{templateId}. Staff. Sends Ken-Version 1.1.
A template in another workspace is 404.
get-version
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/versions/{versionId}
Path: templateId, versionId
Return one Studio template version with its file list, manifest and validation. File contents come from pull, not here.
GET /api/v1/asset-templates/{templateId}/versions/{versionId}. Staff. Sends
Ken-Version 1.1.
get-webhook-secret
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/webhook-secret
Path: templateId
Return the signing secret of a Studio template's webhook steps, so the customer's endpoint can verify calls. The secret is a credential: give it only to the endpoint that receives the template's webhook calls.
GET /api/v1/asset-templates/{templateId}/webhook-secret. Staff. Sends Ken-Version 1.1. Requires
Studio view and the `integrations` permission (admins by default). Answers {templateId, secret, scheme: "standard_webhooks"}. The first read creates the
template's secret (whsec_ plus base64 of 32 random bytes); every later read returns the same one.
Each webhook step call is signed Standard Webhooks style: headers webhook-id, webhook-timestamp and
webhook-signature ("v1," plus base64 HMAC-SHA256 over "{id}.{timestamp}.{body}" with the decoded
key), so any Standard Webhooks library verifies it with this secret. A template in another
workspace is 404, and no secret is created for it.
datasets-list
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/datasets
Path: templateId
List a Studio template's CSV datasets by name, with header columns and row counts.
GET /api/v1/asset-templates/{templateId}/datasets. Staff. Sends Ken-Version 1.1.
One page: every dataset of the template.
list
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates
Query: cursor string, limit integer, type string
List the workspace's Studio templates, newest first, with uses and live page counts.
GET /api/v1/asset-templates. Staff. Sends Ken-Version 1.1. template_type filters by type: reverse_demo, landing_page, audit, report, event, calculator, recruiting, other. Each item carries uses (pages built from it) and livePages; meetings and replies stay null until attribution ships. limit 1 to 200. Pass pagination.nextCursor back unchanged with the same filter.
starters-list
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/studio/starters
Query: category string, featured boolean, needs string, q string, type string
Search the Kenso template library: templates every workspace can preview and fork. Read one with studio_docs starters-get. Copy one with create and starter_slug.
GET /api/v1/studio/starters. Staff. Sends Ken-Version 1.1. One page: every
library template that matches. Each has slug, name, type, format, description,
category, tags, featured, needs, updatedAt, coverUrl (a 1280x800 PNG) and
samples [{id, label, url}]. Each sample url is the HTML of the sample rendered to a full
page. raw.githubusercontent.com serves it as text/plain, so fetch the text to read or
show it (a sandboxed srcdoc iframe); opened as a link it shows source, not a page.
q: free text over name, tags, description and category. A name match ranks first,
then a tag match, then a description or category match. Without q, featured
templates come first, then by name.
type: reverse_demo, landing_page, audit, report, event, calculator, recruiting or
other. category: prospecting, deal, events, customers, interactive, content,
partners or recruiting. needs: none (ready to use) or dataset, webhook, knowledge,
video. featured: true keeps featured templates only. A type or needs outside those
values is refused; an unknown category returns an empty list. 503 when the starter
repo cannot be read; retry later.
list-versions
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/versions
Path: templateId
Query: cursor string, limit integer
List a Studio template's versions, newest first, with who built and published each.
GET /api/v1/asset-templates/{templateId}/versions. Staff. Sends Ken-Version 1.1.
Each version carries its status (draft or published), builtBy (ken or
customer_agent) and validation summary. builtBy is self-reported (from the
pushing client's declared name), a label rather than proof of who built it.
limit 1 to 200. Pass pagination.nextCursor back unchanged.
preview
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/preview
Path: templateId
Body (json): accountIds array, interact array, mode string, sample string, versionId integer
Preview a Studio template version for up to 3 samples: signed URLs, screenshots, link issues. Takes up to a minute per sample. Writes nothing to the database.
POST /api/v1/asset-templates/{templateId}/preview. Staff. Sends Ken-Version 1.1.
Requires Studio edit.
version_id: the version to render; defaults to the draft, else the latest published.
account_ids: up to 3 account ids of this workspace. Default: the 3 most recently
touched accounts, else the bundle's samples/*.json, else one render with slot fallbacks.
An account with no page on this template renders every slot on its fallback.
sample: a samples/<name>.json path of the version, such as "samples/fernway.json". Its
data fills the slots on each account, with that account's Kenso variables (account, person,
sender, brand), so you see the filled layout before any page exists. With no account to
render on, the sample renders alone. Leave it out to see each account's own page, or the
fallback before the fill.
mode: "render" (default) or "interact". Sending interact steps alone means "interact".
interact: up to 20 steps run in order before one more desktop screenshot:
{"action": "click", "selector": "#cta"} | {"action": "type", "selector": "#revenue",
"value": "120000"} | {"action": "wait", "ms": 500}. selector at most 200 characters,
value at most 1,000, ms 1 to 10,000.
An email template (format email) renders in Kenso, not on the edge, and returns
data.emailPreviews[] instead of data.previews[]: one per bundle sample (up to 3, or the
one sample named), else one fallback render, each {sample {kind: sample|fallback, name},
subject, html, text, issues[]} (issues: liquid-parse:..., liquid-render:...,
removed:<what> for markup the sanitizer took out, email-size). The Kenso tokens
({{unsubscribe_link}}, {{tracking_link:N}}, {{asset_link}}, {{booking_url}},
{sender_first_name}) stay as written; they are filled at send. account_ids, mode and
interact do not apply to an email (400).
Returns data.previews[]: {previewId, accountId, sample {kind: account|sample|fallback,
name: the sample used, also on an account previewed with sample; null for an account's
own page}, url (signed, valid 24 h, on the workspace's own host; null when it has none, or
when the sample links to a blocked host), reason (no_workspace_host, link_safety_flagged,
screenshot_failed or null), screenshots {desktop, mobile}
(presigned PNG URLs valid 1 h, null when that shot failed), consoleErrors, interact
{steps [{ok, error}], finalScreenshot}}, plus data.expiresAt and data.linkIssues
[{rule, severity, url, domain, message}] (link-domain-blocked and link-domain-new are
errors that block a publish; link-check-unavailable is a warning).
Errors to handle:
- 400 validation_failed: each detail names the field (accountIds[1], interact[0].ms,
sample: not_found lists the version's samples in allowed).
- 409 invalid_state: no_version (push a bundle first) or render_failed (fix the bundle).
- 429: 200 previews a day per workspace. Wait for quotaResetAt.
- 503: previews are not configured or R2 failed. Nothing was rendered; retry.
publish
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/publish
Path: templateId
Body (json): updateLive any JSON, versionId integer
Publish a Studio template's draft (or version_id) so new pages use it. Refused while validation has errors or a link is flagged. update_live refills live pages.
POST /api/v1/asset-templates/{templateId}/publish. Staff. Sends Ken-Version 1.1.
Requires Studio edit.
version_id: the draft to publish; defaults to the template's draft.
update_live: "none" (default), "all", or a list of live page ids to refill on
the new version; the response then carries updateRunId. One publish refills at
most 500 pages, and the refill run passes the checks of any fill run: the
balance must cover its estimate, and each page takes one unit of the daily
studioRunAsset quota. A live page with its own layout whose merge with the new
version clashes is left out of the refill (not charged), flagged (layoutConflict
on studio_pages get) and listed in skipped with reason layout_conflict: ask the
user, then answer it with studio_pages(operation="update-version", asset_id=...,
layout="keep") or layout="take". Pages that follow the
latest version move to it either way: the response returns followedCount right
after the publish commits, and their pages refresh in the background. A page
that already has data moves only when the version reruns none of its steps;
otherwise it moves with its next run or refill.
Every external link in the bundle (https://, http:// and //host, backslash forms
included) is checked; a publish holds at most 2000 distinct links.
Errors to handle:
- 409 invalid_state: validation has errors (each detail has field file:line and
code = the rule) or a link is flagged. Fix with push, validate, then publish.
- 409 invalid_state (too_many_links): the version links to more than 2000
distinct URLs. Remove links, push, then publish.
- 409 invalid_state (draft_incomplete): the last push to the draft was cut off
before it finished. Push again, then publish.
- 409 conflict (concurrent_change): a push landed while publish read the draft. Retry.
- 400 validation_error (updateLive too_many): update_live covers more than 500
live pages. Send at most 500 page ids, then move the rest with
studio_pages(operation="update-version").
- 402: the balance cannot cover the refill run. Nothing changed; top up or send
fewer page ids.
- 429: 50 publishes a day per workspace, or the daily studioRunAsset quota has
no room for the refill run's pages. Wait for the next day.
- 503: the edge could not take the version. Nothing changed; retry.
pull
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/pull
Path: templateId
Query: version string
Read a Studio template's bundle files back for editing. Default: the draft, else the latest published version. Text inline, binaries as downloadUrl.
GET /api/v1/asset-templates/{templateId}/pull. Staff. Sends Ken-Version 1.1.
version: draft, latest (the latest published) or a version id. Text files come
inline as text. Binaries come as a downloadUrl valid for 15 minutes: fetch it
then, or pull again. Edit the files and send them back with push.
409 conflict (concurrent_change): a push landed while the files were read. Pull again.
The pull returns bundleSha256 (the bundle's token for push expected) and updatedAt.
Take expected from a pull without version (the draft): a latest or version-id pull
gives a token push accepts only while the template has no draft.
push
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/push
Path: templateId
Body (json): builtBy string, deleteMissing boolean, expected string, files object, message string
Write files into a Studio template's draft. Returns the draft and its validation. text_files maps a path to its text; files maps a path to {text}, {uploadId} or {fromUrl}.
POST /api/v1/asset-templates/{templateId}/push. Staff. Sends Ken-Version 1.1.
Requires Studio edit. Send files, text_files, or both (each path once).
text_files: bundle path to the file's text, for studio.json, *.liquid, CSS, SVG
and samples. The easy way to push files you wrote: {"studio.json": "{...}"}.
files: bundle path (forward slashes, no leading slash) to exactly one of
{"text": "..."} for text files, {"uploadId": "..."} for a binary uploaded
through create-upload-url, or {"fromUrl": "https://..."} for a public https
file Kenso fetches (5 MB, 10 seconds). Unlisted files stay in the draft.
The map is sent as given. A push holds at most 300 files, 20 fromUrl files and
20 MB in total.
delete_missing=true makes the draft hold exactly these files; by default the
files are added or replaced and the rest kept. message: what changed, up to
500 characters. built_by: customer_agent labels the push; it never upgrades one
to ken. builtBy is self-reported, a label for the version history only.
When the latest version is published, the push starts draft N+1. A bundle with
validation errors is still stored: read validation in the response and fix the
errors before publish (each issue names file:line and the rule).
expected: the bundleSha256 from your pull without version (the draft), or from the
last push's version.bundleSha256. 409 conflict (concurrent_change) means the draft
changed since, in the editor or by another agent: pull again, re-apply your change,
push with the new bundleSha256. Without expected, the last write wins.
restore-version
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/versions/{versionId}/restore
Path: templateId, versionId
Body (json): message string
Restore an older published version: the draft holds exactly its files, as a new version. Returns the draft and its validation, as push does. Publish it to make it live.
POST /api/v1/asset-templates/{templateId}/versions/{versionId}/restore. Staff. Sends
Ken-Version 1.1. Requires Studio edit. version_id: a published version from
list-versions. The draft (draft N+1 when the latest version is published) gets that
version's files, binaries included, is validated again, and records
restoredFromVersionId. An unpublished draft's files are replaced. message: up to 500
characters, default "Restored from v{n}". Live pages and the published version do not
change until publish (with the update_live you want). 409 invalid_state
(version_not_published) when version_id is the draft itself. 404 when the template or
version is not in this workspace.
update
Write. Early access: needs studio on for the workspace. PATCH https://api.ken.so/v1/asset-templates/{templateId}
Path: templateId
Body (json): description string, format string, name string, slug string, type string
Update a Studio template's name, description, type, format or slug. Absent fields stay unchanged; null clears one. Files change through push, not here.
PATCH /api/v1/asset-templates/{templateId}. Staff. Sends Ken-Version 1.1. Requires
Studio edit. changes keys: name, description, type, format, slug, with the values
create takes. Unknown keys fail before the call.
validate
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/asset-templates/{templateId}/validate
Path: templateId
Body (json): deleteMissing boolean, files object
Validate a Studio template's draft, or files laid over it, without storing files. No files validates the stored draft and records the result on it.
POST /api/v1/asset-templates/{templateId}/validate. Staff. Sends Ken-Version 1.1.
Requires Studio edit.
Without files: validates the stored draft (else the latest published version)
and records the result on a draft. With files and/or text_files (same shapes as
push): validates them merged over the draft as a push would, and stores nothing.
delete_missing=true validates exactly files, ignoring the draft.
Each issue names file:line and the rule. Publish refuses while errors remain.
Without files: 409 invalid_state (draft_incomplete) when the last push to the
draft was cut off. Push again. 409 conflict (concurrent_change): a push landed
while the draft was read. Retry.