Studio Docs studio_docs
Studio doc pages as files to forward: make a doc page from text you wrote (a report), and export a doc page as a Google Doc or Word file in the member's own drive. starters-get reads one Kenso library template (studio_templates starters-list finds them). template-slots-list lists a template's slots, the keys a studio.page@1 step's slots takes. Also: upload an image for one page's own layout (create-upload-url), import one from the member's Google Drive or OneDrive or an https URL for a page or template (create-image-upload), and the workspace brand kit (colors, fonts, logos) Studio pages, docs and templates style with: read it, change it, or suggest one from the website.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through studio_docs_read and changes through studio_docs_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: create-doc, create-doc-export, create-image-upload, create-upload-url, brand-kit-get, starters-get, list-doc-exports, template-slots-list, brand-kit-suggest, brand-kit-update
create-doc
Write. Early access: needs rd_docs, studio on for the workspace. POST https://api.ken.so/v1/assets/docs
Body (json): markdown string, title string
Make a Studio doc page from text you already wrote (Markdown or report sections), optionally shared as a link. No template, fill or prepare. Full docs: describe_tools(['api_assets_create_doc'])
POST /api/v1/assets/docs. Staff, and the workspace needs the studio and rd_docs flags.
Sends Ken-Version 1.1 and X-Ken-Actor: agent. title is 1 to 200 characters. Send markdown,
sections (up to 30 objects {heading, body}: each becomes a ## heading with its body as
Markdown, after markdown when both are sent), or both; at most 100,000 characters in all.
Kenso renders headings, paragraphs, lists, quotes, code, pipe tables, bold, italic and https
links; raw HTML stays text. The page sits on the workspace's "Text docs" template, which the
first call creates and publishes, is branded with the workspace's white-label brand and is
ready at once. Making it charges no credit. Returns the page (data.id is the asset_id).
Text the page refuses is a 400 naming the rule, and nothing is made: an email address or
phone number (a page may show only the sender's), an http link or a link shortener.
provider shares the new doc in the same call and returns data.share:
- google_drive or onedrive: the export studio_docs(operation="create-doc-export",
asset_id=901, provider="google_drive") runs on it. A Google Doc in the calling member's
Drive that anyone with the link can comment on, or a Word file in their OneDrive with an
anonymous view link. Neither link expires; it lasts until the member deletes or unshares
the file. Needs the member's Kenso Workspace connection; the export's refusals apply.
- studio_page: the page's shared Studio link (studio_pages(operation="create-link",
asset_id=901, shared=True)). The HTML page on the workspace's own link domain, open to
anyone with the link, with a Download PDF button. The first link publishes the page and
charges 1 credit. A live page that gets no visits for 30 days retires; republish it.
Leave provider out to get only the page and share it later with those operations. When the
share fails, the page is still made: the error names its asset_id.
create-doc-export
Write. Early access: needs rd_docs, studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/doc-exports
Path: assetId
Body (json): provider string
Export a doc page to Google Docs or Word in the calling member's own drive and share it by link. Exporting again updates the same file. Full docs: describe_tools(['api_assets_create_doc_export'])
POST /api/v1/assets/{assetId}/doc-exports. Staff, and the workspace needs the rd_docs
flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. provider is google_drive (a
Google Doc in "Ken reverse demos", anyone with the link can comment) or onedrive (a
Word file in /Ken/Reverse demos, anonymous view link). The file goes into the
calling member's own Kenso Workspace connection for that provider. 201 when the URL
is new (first export, another member's export, or a file deleted and made again);
200 when the same member exports again and the same file and URL get the new
content. The export itself charges no credit. If the account's
admin refuses public sharing, the private file is deleted and the page's shared
Studio link is returned (status studio_page, fallbackReason sharing_blocked); the
first Studio link charges 1 credit. On a campaign page the URL goes into rd_link on
that company's leads (leadsUpdated; rdLinkSkippedReason custom_variable_limit when
the campaign's 50 custom variables leave no room).
Errors: 409 doc_format_required (the template is a web page, not a doc),
asset_not_ready (not ready or live), connection_required (connect the provider in
Kenso Workspace), reconnect_required (reconnect and allow file access),
studio_no_host (set up link tracking on a sending domain), export_in_progress
(another export of this page to this provider is running; retry after it ends).
413 doc_too_large (over Google's 5 MB or OneDrive's 4 MB upload cap: use fewer or
smaller images; do not retry as is). 429 daily_limit_reached (250 new shared docs
per connection per UTC day). 502 provider_error and 503 render_unavailable: retry
in a minute.
create-image-upload
Write. Early access: needs connected_app_reads, studio on for the workspace. POST https://api.ken.so/v1/assets/image-uploads
Body (json): name string, source object
Import one image into Studio from the member's Google Drive or OneDrive file, or from an https image URL. Kenso fetches the image itself, so never pass image bytes. Use the returned uploadId and path in customize or push.
POST /api/v1/assets/image-uploads. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Give exactly one source: url (an https image address, for example one a connected tool
returned), or provider ("google" or "microsoft") with file_id (an id cloud_files search
returned). name is an optional file name for the image (acme-logo); without it the
source's own file name is used. PNG, JPEG, GIF, WebP or AVIF up to 5 MB, decided from the
bytes; SVG is refused. Returns uploadId, path, contentType and sizeBytes. The upload is
kept for one day and is used once. Put it on one page with
studio_pages(operation="customize", asset_id=901, layout={"template": "<the edited template>",
"files": {"assets/acme-logo-1a2b3c4d5e6f.png": {"uploadId": "<uploadId>"}}},
expected="<source.token>"), where the template shows it as
<img src="{{ asset_url | append: '/acme-logo-1a2b3c4d5e6f.png' }}" alt="">; use the returned
path, not a name you choose. Or put it in a template with studio_templates(operation="push",
template_id=..., files={"<path>": {"uploadId": "<uploadId>"}}). Errors: 400
validation_failed (a bad source, or a URL that is not public https), 404 when Kenso cannot
see the file, 409 google_not_connected or microsoft_not_connected, 422 unsupported_image,
image_too_large, fetch_failed (the URL did not answer, answered an error, redirected more
than 3 times or to a private address) or demo_workspace, 503 storage_failed.
create-upload-url
Write. Early access: needs studio on for the workspace. POST https://api.ken.so/v1/assets/{assetId}/upload-urls
Path: assetId
Body (json): bytes integer, contentType string, path string
Get a presigned URL to upload one image for one Studio page's own layout (5 MB max). PUT the file to url with the returned headers, then save it with customize under the returned path.
POST /api/v1/assets/{assetId}/upload-urls. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
The page twin of studio_templates(operation="create-upload-url"): the file belongs to this
page only, never to its template. path: assets/<name>, a png, jpg, gif, webp or avif file
(assets/hero.png). 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. Returns uploadId, url,
expiresAt, headers, maxBytes and path. PUT the bytes to url with exactly those headers
within 15 minutes. path is the name the API gave the image (assets/<name>-<12 hex>.<ext>,
so another prospect cannot guess its URL): use its path, not the one you asked for, as the
layout.files key and in the template. Then save it: studio_pages(operation="customize",
asset_id=901, layout={"template": "<the edited template>", "files":
{"assets/hero-1a2b3c4d5e6f.png": {"uploadId": "..."}}}, expected="<source.token>"), where
the template shows it as <img src="{{ asset_url | append: '/hero-1a2b3c4d5e6f.png' }}" alt="">.
Any other key for a new upload is 400 invalid_path.
brand-kit-get
Read. Early access: needs brand_kit on for the workspace. GET https://api.ken.so/v1/workspaces/{workspaceId}/brand-kit
Path: workspaceId
Read the workspace brand kit: the two colors, two fonts and logos Studio pages, docs and templates use.
GET /api/v1/workspaces/{workspaceId}/brand-kit with Ken-Version 1.1, for the workspace in
X-Ken-Workspace-Id (client_id, else the pinned workspace).
data fields (unset ones are omitted):
- primaryColor, accentColor: hex colors, #RRGGBB uppercase.
- headingFont, bodyFont: Google Fonts families in Google's spelling, such as "Space Grotesk".
- iconUrl: the square logo. logoUrl: the wide logo. Both on Kenso's media host.
- autofilledAt (ISO 8601 UTC) and autofillSourceUrl: set while the kit is as Ken filled it from
the website; a person's save clears them.
- isEmpty: true when no color and no font is set (the logos do not count).
A Studio template reads the kit as brand.colors.primary, brand.colors.accent,
brand.fonts.heading, brand.fonts.body, brand.logo_url, brand.icon_url and brand.name.
When isEmpty is true, offer studio_docs(operation="brand-kit-suggest") and save only what
the user agrees to.
The workspace needs the brand_kit flag: while it is off the call is 404 not_found.
starters-get
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/studio/starters/{slug}
Path: slug
Read one Kenso library template: its sections and what each recipe step does. Copy it with studio_templates create and starter_slug.
GET /api/v1/studio/starters/{slug}. Staff. Sends Ken-Version 1.1. slug: a slug
from studio_templates starters-list (lowercase letters, digits and hyphens, up to
64). Returns the list fields plus sections [{id, label}] from studio.json and
recipe [{kind, tool, summary}], one entry per step: tool is set only on a tool
step, summary is one plain sentence ("Finds people with Kenso Search"). 404 when the
slug is not in the library. 503 when the starter repo cannot be read; retry later.
list-doc-exports
Read. Early access: needs rd_docs, studio on for the workspace. GET https://api.ken.so/v1/assets/{assetId}/doc-exports
Path: assetId
Query: cursor string, limit integer
List a doc page's exports to Google Docs or Word: one per provider, its URL and comment count.
GET /api/v1/assets/{assetId}/doc-exports. Staff, and the workspace needs the rd_docs
flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. limit 1 to 200. Pass
pagination.nextCursor back unchanged. status is shared (url is the Google Doc or
OneDrive link) or studio_page (sharing was refused; url is the page's shared Studio
link). commentCount counts comments by others on a Google Doc.
template-slots-list
Read. Early access: needs studio on for the workspace. GET https://api.ken.so/v1/asset-templates/{templateId}/slots
Path: templateId
List the slots of a Studio template's published version: name, type and the rules a value must meet. The names are the keys a studio.page@1 workflow step's slots takes.
GET /api/v1/asset-templates/{templateId}/slots. Staff. Sends Ken-Version 1.1.
Reads the latest published version, the one a new page fills, in
studio.json order. A studio.page@1 step that refills an account's existing
page fills on that page's pinned version, which may lack slots added since;
the step drops those with a warning. Each slot carries name, type (string,
integer, number, boolean, array or object), itemType for an array, title
and description when studio.json has them, isRequired, hasFallback (the page
shows the fallback when the slot has no valid value), isFilledByRecipe (a
recipe step writes it, so Ken's fill writes it when the step gives no value)
and the rules a given value is checked against: minLength, maxLength,
format, allowedValues. One page: every slot of the version. A template with
no published version is 409 invalid_state (studio_template_not_published);
a template in another workspace is 404.
brand-kit-suggest
Read. Early access: needs brand_kit on for the workspace. POST https://api.ken.so/v1/workspaces/{workspaceId}/brand-kit/suggestions
Path: workspaceId
Suggest a brand kit from the workspace website. Saves nothing.
POST /api/v1/workspaces/{workspaceId}/brand-kit/suggestions with Ken-Version 1.1. Needs the
workspace settings permission.
Reads the workspace's website and returns, in the formats brand-kit-update takes:
found, sourceUrl, primaryColor, accentColor, headingFont, bodyFont and logoUrl (an image URL
on the website; pass it as logo_source_url to save it). When found is false, reason says why:
- no_website: the workspace has no website. Set it with workspace operation update.
- nothing_found: the website gave no usable color, font or logo.
- unavailable: the website could not be read right now. Try again later.
Nothing is saved. Show the suggestion and save only what the user agrees to, with
studio_docs(operation="brand-kit-update", fill_empty_only=True, ...) so their own choices stay.
Each call is free, never charged to the workspace, and counts on
the workspace's limit of 10 suggestions an hour (past it, 429 quota_exceeded with Retry-After).
The workspace needs the brand_kit flag: while it is off the call is 404 not_found.
brand-kit-update
Write. Early access: needs brand_kit on for the workspace. PATCH https://api.ken.so/v1/workspaces/{workspaceId}/brand-kit
Path: workspaceId
Body (json): accentColor string, bodyFont string, fillEmptyOnly boolean, headingFont string, logoSourceUrl string, primaryColor string
Change the workspace brand kit: colors, Google Fonts and the wide logo from an image URL. Pass only the fields to change; fill_empty_only=True writes only fields that are empty.
PATCH /api/v1/workspaces/{workspaceId}/brand-kit with Ken-Version 1.1. Needs the workspace
settings permission (as a workspace update). Returns the kit as brand-kit-get does.
Fields (a field left out stays as it is; an empty string "" clears it):
- primary_color, accent_color: hex colors, #RGB or #RRGGBB, any case, # optional, such as
"#4F00D0". Stored as #RRGGBB uppercase. Anything else is 400 validation_failed on that
field: "Use a hex color like #4F00D0."
- heading_font, body_font: Google Fonts families, any case, such as "Space Grotesk" or
"Inter". Stored in Google's spelling. Anything else is 400 on that field: "Pick a Google
Fonts family." One invalid field writes nothing.
- logo_source_url: a public PNG, JPEG, WebP or SVG image URL Kenso imports as the wide logo
(an SVG is converted to PNG; the image is stored on Kenso's media host). A failed import is
400 validation_failed on logoSourceUrl with the reason, after the colors and fonts in the
same call were saved. Remove the wide logo with members operation workspaces-delete-wordmark.
fill_empty_only:
- left out or False: a person's save. The sent fields overwrite, and a color or font change
clears autofilledAt and autofillSourceUrl.
- True: writes only the sent fields that are empty now, keeps autofilledAt and
autofillSourceUrl, and imports logo_source_url only when the workspace has no wide logo.
Use it to apply a brand-kit-suggest result the user agreed to without overwriting their
choices.
The workspace needs the brand_kit flag: while it is off the call is 404 not_found.