Knowledge Prompts knowledge_prompts
Knowledge prompts: the workspace's qualification, scoring, research, personalization and replies prompts, each applied to everyone, an account tier (1 to 10) or a campaign segment. For each lead the most specific one of a type wins: segment, then tier, then everyone. Research has no segment (account tier, else everyone) and the reply agent always gets the everyone prompt. campaign-resolution-list shows what each segment of a campaign gets. link-knowledge-prompt links an AI variable to a prompt (copying its body); a workflow AI step links one through with.knowledgePromptId in its draft. A body update then rewrites every linked AI variable and draft step still synced to it; usedIn lists both.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through knowledge_prompts_read and changes through knowledge_prompts_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, delete, get, knowledge-files-keep-edits, link-knowledge-prompt, campaign-resolution-list, list, knowledge-files-reset, restore, unlink-knowledge-prompt, update
create
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/prompts
Body (json): appliesTo array, body string, model string, name string, tierDescriptions array, type string
Create a Knowledge prompt. Returns 201 with the prompt.
POST /api/v1/knowledge/prompts. Needs the knowledge flag. Sends Ken-Version 1.1. name (1 to 200
characters) and type (qualification, scoring, research, personalization, replies, tiers) are
required. body is the prompt text, up to 20,000 characters (default empty). model: cheap, balanced
(default) or smart. applies_to lists up to 50 audiences: {"kind": "everyone"}, {"kind": "tier", "tier": 1-10} or
{"kind": "segment", "segment_id": 55}. A segment must be a live segment of a live campaign in this
workspace; its campaign comes from the segment. With no audience the prompt runs only where an AI
variable or a workflow step links it: create a template that way (to save a workflow step's text as a
template, create it with applies_to [] and then set the step's with.knowledgePromptId to the new id
with workflows(operation="update")). A personalization prompt with an audience is also added to every
line written for that audience. For each lead the most specific prompt of a type wins: segment, then
tier, then everyone. A tiers prompt places accounts in the account tiers (custom tiers): it applies to
everyone or tiers only, and tier_descriptions ([{"tier": 1, "text": "Who belongs in Tier 1"}], tiers
1 to 10, each once, up to 1,000 characters) describe who belongs in each tier; only a tiers prompt
takes them. Needs Knowledge edit.
delete
Write. Early access: needs knowledge on for the workspace. DELETE https://api.ken.so/v1/knowledge/prompts/{knowledgePromptId}
Path: knowledgePromptId
Delete a Knowledge prompt. Soft: restore undoes it.
DELETE /api/v1/knowledge/prompts/{knowledgePromptId}. Needs the knowledge flag. Sends Ken-Version
1.1. Returns 204. Linked AI variables keep their text and read as unlinked while it is deleted; it
stops resolving for every campaign. Linked workflow steps keep their text and their link, and still
save and publish. Needs Knowledge edit.
get
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/prompts/{knowledgePromptId}
Path: knowledgePromptId
Return one Knowledge prompt with its body, audiences, linked AI variables and linked workflow steps.
GET /api/v1/knowledge/prompts/{knowledgePromptId}. Needs the knowledge flag. Sends Ken-Version
1.1. A deleted prompt, or one in another workspace, is 404. Needs Knowledge view.
knowledge-files-keep-edits
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/files/{fileId}/keep-edits
Path: fileId
Body (json): baseVersion integer
Keep your edits to one of Kenso's skills over Kenso's latest update, so it stops showing as an update.
POST /api/v1/knowledge/files/{fileId}/keep-edits. Needs the knowledge flag. Sends Ken-Version 1.1.
base_version is the file's current version (from get); a stale one is version_conflict. Leaves the
body as it is and marks Kenso's current text as seen: kenSkillUpdateAvailable turns false until Kenso
ships a newer version. Writes no version. A file with no update waiting comes back unchanged. Only
Kenso's skills can do this; any other file is 409 invalid_state.
link-knowledge-prompt
Write. Early access: needs knowledge on for the workspace. PUT https://api.ken.so/v1/prompts/{promptId}/knowledge-prompt
Path: promptId
Body (json): knowledgePromptId integer
Link an AI variable to a Knowledge prompt and copy the prompt's body into it, so it starts synced.
PUT /api/v1/prompts/{promptId}/knowledge-prompt with {"knowledgePromptId": ...}. Needs the knowledge flag.
Sends Ken-Version 1.1. prompt_id is the AI variable (a personalization prompt; prompts(operation="list")
finds it); another flow is 400, and so is a Knowledge prompt with no text yet. Linking an edited AI variable
again to the same prompt reverts it to the body. Returns {promptId, knowledgePromptId, name, text, state}.
Needs campaign edit, and Knowledge view because the link copies the prompt's body.
campaign-resolution-list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/knowledge-prompts
Path: campaignId
Show which Knowledge prompt each type resolves to in a campaign, per segment and for leads with no segment.
GET /api/v1/campaigns/{campaignId}/knowledge-prompts. Needs the knowledge flag. Sends Ken-Version 1.1.
One item per type (qualification, scoring, research, personalization, replies) for each live segment
in sort order, then one with segmentId null for leads with no segment (personalization runs those
leads as the campaign's default segment, so that row resolves with its prompts). Scoring runs: lead
scoring adds the prompt that wins for the lead's segment and tier, so it resolves like qualification.
Replies and research resolve with no segment on every row: the reply agent always gets the everyone
prompt, and account research and the workflow research step pick by the account's tier, else everyone.
match is segment, everyone or none (prompt null). tierPrompts names, per tier 1 to 10, the tier prompt
that beats the everyone prompt for leads in that tier; it is empty when a segment prompt wins. A
campaign in another workspace is 404. Needs campaign view.
list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/prompts
Query: type string
List the workspace's Knowledge prompts with their audiences and their linked AI variables and workflow steps.
GET /api/v1/knowledge/prompts. Needs the knowledge flag. Sends Ken-Version 1.1. One page in id
order, the order ties resolve in. type filters to qualification, scoring, research, personalization,
replies or tiers. Each prompt has appliesTo (everyone, tier 1 to 10, or a segment with its campaign and
segment names), tierDescriptions on a tiers prompt ({tier, text}: who belongs in each tier) and usedIn: the linked AI variables (kind ai_variable), then the linked workflow AI
steps (kind workflow_step, with workflowId, workflowName, versionId, versionNumber, versionStatus
draft or published, stepId, stepName and stepType) of each live workflow's draft and published
version. Each use is synced (its text equals the body) or edited (changed there). Needs Knowledge
view.
knowledge-files-reset
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/files/{fileId}/reset
Path: fileId
Body (json): baseVersion integer
Reset one of Kenso's skills in Knowledge > Skills to Kenso's current version. It becomes a new version.
POST /api/v1/knowledge/files/{fileId}/reset. Needs the knowledge flag. Sends Ken-Version 1.1.
base_version is the file's current version (from get); a stale one is version_conflict. Replaces
the body with Kenso's text and saves it as a new version ("Reset <name> to Ken's version"), so the
edits stay in versions-list. Only Kenso's skills (kenSkill on the file) can be reset; any other file,
or a skill Kenso no longer ships, is 409 invalid_state. Needs the same permission as editing the file.
restore
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/prompts/{knowledgePromptId}/restore
Path: knowledgePromptId
Restore a deleted Knowledge prompt, which brings its links back.
POST /api/v1/knowledge/prompts/{knowledgePromptId}/restore. Needs the knowledge flag. Sends
Ken-Version 1.1. Restoring a prompt that is not deleted changes nothing. Needs Knowledge edit.
unlink-knowledge-prompt
Write. Early access: needs knowledge on for the workspace. DELETE https://api.ken.so/v1/prompts/{promptId}/knowledge-prompt
Path: promptId
Unlink an AI variable from its Knowledge prompt. It keeps its text.
DELETE /api/v1/prompts/{promptId}/knowledge-prompt. Needs the knowledge flag. Sends Ken-Version
1.1. Returns 204. Unlinking an AI variable with no link changes nothing. Needs campaign edit.
update
Write. Early access: needs knowledge on for the workspace. PATCH https://api.ken.so/v1/knowledge/prompts/{knowledgePromptId}
Path: knowledgePromptId
Body (json): appliesTo array, body string, model string, name string, tierDescriptions array, type string
Change a Knowledge prompt. A new body also goes to every synced AI variable and draft workflow step.
PATCH /api/v1/knowledge/prompts/{knowledgePromptId}. Needs the knowledge flag. Sends Ken-Version 1.1.
Send any of name, type, body, model, applies_to (which replaces the audiences; [] clears them) and
tier_descriptions (a tiers prompt only; replaces them, [] clears them); omitted fields stay. A new body is copied, in the same transaction, to each linked AI variable whose
text still equals the old body, and to each linked AI step whose text still equals it in a workflow's
draft (a published version never changes and no draft is created; the draft's draftVersion goes up).
AI variables and steps edited where they live keep their text. syncedRows in the response counts
both, and syncedSteps counts the workflow steps. Clearing the body is a 400 while synced AI variables
or workflow steps run it. Needs Knowledge edit.