Knowledge knowledge
What Kenso knows about this workspace, its users and its accounts, with a source on every item. Call context first: one call returns the cited pack for an account or person. Use search only for what the pack does not cover. To edit a file, get it, then update with its version as base_version. Where you cannot edit, use suggestion-create.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through knowledge_read and changes through knowledge_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: context, create, suggestion-create, transcripts-create, writing-style-create, hubspot-create-connect-session, transcripts-create-email-address, transcripts-create-webhook, delete, get, versions-list, list, folders-list, website-pages-list, website-pages-refresh, writing-style-relearn, website-pages-replace, versions-restore, search, update
context
Read. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/context
Body (json): account string, accountId integer, budgetTokens integer, personId integer, purpose string, skill string
Call this first: the cited Knowledge pack for an account, a person or the workspace, in one call.
POST /api/v1/knowledge/context with {accountId?, account?, personId?,
skill?, purpose?, budgetTokens?}. Needs the knowledge flag. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Call it before any other Knowledge
call: most work needs nothing else, and search is only for what the pack
does not cover. Name the account by account_id, or by account: a domain,
URL, email or name. No match is 404 account_not_found; more than one is
409 account_ambiguous with up to 5 candidates (accountId, domainName) in
error.details: pick one and call again with its account_id. person_id adds
the person's file and, when the person is on exactly one account and you
named none, that account. skill is a skill file id, its command
(follow-up) or knowledge/<command>; purpose says what the pack is for and
steers which files and facts come first. budget_tokens caps the scoped
part (1 to 8000, default 3000). The pack always includes evidence, so
include_evidence is optional here and only true is accepted; false is
refused (search with include_evidence false returns facts only).
Returns {data: {accountId, personId,
stable, scoped, stableTokens, scopedTokens, budgetTokens, truncated}}.
stable (instructions, the skill, company files, your About me and Writing
style) is the same for every account; scoped holds the account's and
person's files, signals, recent touches, the top facts and evidence
excerpts (kind evidence: dated quotes from its messages and documents,
newest first). Each item is {citationId, kind, title, text, asOf,
sourceDate, sourceUrls, stale}: cite citationId, and treat stale items
(older than 90 days) with care. Private items appear only in your own
pack. This read changes nothing and makes no model call.
create
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/files
Body (json): active boolean, body string, cmd string, description string, folderId integer, name string, status string, tags array, trigger string, visibility string
Create a Knowledge file in a folder. Returns 201 with the file at version 1.
POST /api/v1/knowledge/files. Needs the knowledge flag. Sends Ken-Version 1.1. folder_id (from folders-list) and name (1 to 200 characters) are required. body is the markdown, up to 100,000 characters. tags: a list of tag names (stored lowercased). status: ok (default) or off. visibility: workspace (default) or private (your own skill, instruction or You file). Skills also take active, cmd (the slash name: lowercase words joined by hyphens, up to 40) and trigger (when it runs, in words). A folder you cannot add to is 403 forbidden: propose the file with suggestion-create (kind new_file).
suggestion-create
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/suggestions
Body (json): anchorHeading string, baseVersion integer, fileId integer, folderId integer, kind string, newFileName string, newText string, oldText string, reason string
Suggest a Knowledge change for a person to review, for a file or folder you cannot change.
POST /api/v1/knowledge/suggestions. Needs the knowledge flag. Sends Ken-Version 1.1. kind: change (file_id, old_text, new_text), addition (file_id, new_text) or new_file (folder_id, new_file_name, new_text). base_version is the file version you read (stale is version_conflict). anchor_heading names the section the text is in. reason (up to 1000 characters) shows in Review, where a person with edit rights accepts or dismisses it. Returns 201 with the suggestion, labelled "<user> via <client>".
transcripts-create
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/transcripts
Paste a call transcript into Knowledge. Returns 202 with the import (status processing). Attach it to a meeting (meeting_id) or an account (account_id), or neither. Facts follow in Review.
POST /api/v1/knowledge/transcripts. Needs the knowledge flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. text: the transcript as plain text, or .vtt or .srt content pasted as text, up to 5 MB. "Name: words" lines keep their speaker. meeting_id (optional): mtg_<n>, a meeting you can open in Calendar. The account comes from the meeting. A transcript with no account (none sent and none on the meeting), or on a private meeting, stays yours; one on an account is shared with whoever can see the account. Only the owner of a private meeting can import its transcript. account_id (optional): the account the call was with (accounts tool). With meeting_id, leave it out or send the meeting's account (account_mismatch otherwise). title (optional): up to 200 characters; defaults to the meeting title, else "Call transcript". occurred_at (optional): ISO-8601 instant of the call; defaults to the meeting start, else now. A call older than the workspace retention (6 to 36 months) fails with past_retention. Returns id, status, format, turns, chunks, truncated, meetingId, accountId, title, occurredAt, visibility, evidenceIds (kev_<n>, citable) and createdAt.
writing-style-create
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/writing-style
Start your own Writing style file, so you can add rules before Ken has learned any.
POST /api/v1/knowledge/writing-style. Needs the knowledge flag. Finds or makes the You / Writing style file of the user who connected the agent, the file Ken's writing style learners write to, and returns it with its body and version, as get does. A new file is empty, at version 1. A second call returns the same file unchanged. Add a rule with update (file_id, base_version, and the whole body), one "- rule" line each. It never makes another member's file. 409 member_required for a key with no member, or for staff who are not a member of the workspace. Needs Knowledge edit.
hubspot-create-connect-session
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/hubspot/connect-sessions
Start connecting the workspace's HubSpot CRM to Knowledge. Returns 201 with the authorize URL. A workspace admin opens authorizationUrl and finishes in the web app. Full docs: describe_tools(['api_knowledge_hubspot_create_connect_session'])
POST /api/v1/knowledge/hubspot/connect-sessions. Needs the knowledge flag.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Workspace admins only, with ingestion on for the workspace. Returns authorizationUrl and
expiresAt (about 10 minutes). The admin who opens the link must be the one who finishes
the connect, signed in to the web app, in the same workspace. The link is personal: hand
it only to that admin, never to anyone else. HubSpot returns to Kenso's own app host, never
a white-label host, and the connect finishes only for the admin who started it.
The CRM read scopes are requested as optional. A grant that reads nothing Kenso uses (deals need
contacts or companies too; notes and calls need contacts) ends with reason missing_scope and
connects nothing.
Fails with hubspot_crm_unavailable while the HubSpot app does not offer the CRM scopes,
and ingestion_off while ingestion is off for the workspace.
Disconnect with knowledge_review sources-disconnect (DELETE /v1/knowledge/sources/{id}).
transcripts-create-email-address
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/sources/transcript-email
Make or replace your email-in address. Returns it once: treat it like a password. Forward call recaps or transcripts (a .txt, .vtt, .srt or .docx attached, or the text in the body) to it, and Kenso stores them in Knowledge.
POST /api/v1/knowledge/sources/transcript-email. Needs the knowledge flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. One address per member: calling again replaces it, and mail to the old address bounces from then on (the id stays). The address is in this response only; Kenso keeps a hash of it. Never paste it anywhere shared. A message whose sender or recipients match an account you can see is shared on that account; otherwise it stays yours. The same message again (same Message-ID) is a duplicate and writes nothing, also after you remove it. A workspace key with no person fails with needs_person. While Knowledge is off for the workspace itself, it fails with knowledge_off. Returns id, address, rotated and createdAt.
transcripts-create-webhook
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/sources/transcript-webhook
Make or replace your transcript webhook URL. Returns it once: treat it like a password. Recorders (Otter, tl;dv, Granola, Avoma), Zapier or Make post call transcripts to it, and Kenso stores them in Knowledge.
POST /api/v1/knowledge/sources/transcript-webhook. Needs the knowledge flag.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
One URL per member: calling again replaces it, and the old URL answers 404 from then on (the id stays).
The URL is in this response only; Kenso keeps a hash of its token. Never paste it anywhere shared.
Posting to it needs no other credential: JSON {title?, occurredAt?, attendees?: [{name, email}],
transcript?: string or [{speaker, text}], summary?, externalId?}, at most 2 MB. A call whose attendees
match an account you can see is shared on that account; otherwise it stays yours. The same externalId
(or the same body) again is a duplicate and writes nothing, also after you remove the stored call.
A workspace key with no person fails with needs_person. While Knowledge is off for the workspace itself,
it fails with knowledge_off.
Returns id, url, rotated and createdAt.
delete
Write. Early access: needs knowledge on for the workspace. DELETE https://api.ken.so/v1/knowledge/files/{fileId}
Path: fileId
Query: baseVersion integer
Delete a Knowledge file a person made. Ken's own files cannot be deleted.
DELETE /api/v1/knowledge/files/{fileId}?baseVersion=. Needs the knowledge flag. Sends
Ken-Version 1.1. Returns 204. base_version is the version from get; a stale one is
version_conflict. Ken's own files (the Company and Deal files Ken keeps) answer 409
invalid_state. A file you cannot change is 403; ask a workspace admin.
get
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/files/{fileId}
Path: fileId
Return one Knowledge file with its markdown body and its current version. Pass that version as base_version on update, delete or versions-restore.
GET /api/v1/knowledge/files/{fileId}. Needs the knowledge flag. Sends Ken-Version
1.1. A file the caller cannot see, or one in another workspace, is 404. canEdit says
whether update will be accepted; when it is false, propose the change with
suggestion-create.
versions-list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/files/{fileId}/versions
Path: fileId
Query: cursor string, limit integer
List a Knowledge file's saved versions, newest first, each with its body and author.
GET /api/v1/knowledge/files/{fileId}/versions. Needs the knowledge flag. Sends Ken-Version 1.1.
Each version has version, name, tags, status, changeKind, author ({kind, userId, name, client}:
"Jordan via Claude Code"), sourceLabel, reason, restoredFromVersion, createdAt and bodyMd. limit
1 to 200 (default 50). Pass pagination.nextCursor back unchanged for older versions.
list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/files
Query: accountId integer, active boolean, cursor string, folderId integer, level string, limit integer, personId integer, q string, status string, tag string
List the workspace's Knowledge files, newest first, without their bodies.
GET /api/v1/knowledge/files. Needs the knowledge flag. Sends Ken-Version 1.1. Filters: folder_id (from folders-list), tag, level (org, user, company, deal, prospect, public, skill, instruction), status (reading, ok, off, pending), active (skills and instructions in use), q (literal text in the name or body), account_id, person_id. Files the caller cannot see are left out. limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the same filters. Call get for a file's body and version.
folders-list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/folders
Query: accountId integer, parentId integer
List Knowledge folders: the top level, one folder's children, or an account's folders.
GET /api/v1/knowledge/folders. Needs the knowledge flag. Sends Ken-Version 1.1. With neither filter: the top folders (the company folder named after the workspace, Accounts, You, Skills, Instructions). parent_id lists that folder's children; account_id lists an account's folders. One page, so pagination.hasMore is false. Each folder has canEdit; use its id as folder_id on list and create. knowledge_library makes, renames and deletes folders.
website-pages-list
Read. Early access: needs knowledge on for the workspace. GET https://api.ken.so/v1/knowledge/website/pages
List the pages Ken watches on the workspace's website, with each page's status.
GET /api/v1/knowledge/website/pages. Needs the knowledge flag. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Returns {website, pages,
maxPages}. website is the workspace's site in normal form, or null when
it has none. Each page is {id, url, status, lastCheckedAt, lastChangedAt,
errorCode}, and status is ok, changed, failed or pending. Needs Knowledge
view.
website-pages-refresh
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/website/refresh
Ask Ken to re-read the watched pages now ("Refresh now").
POST /api/v1/knowledge/website/refresh. Needs the knowledge flag. Returns
202 {queued: true} at once. Ken maps the website (unless 15 pages are
already watched), adds the pages it picks (never one a person removed) and
re-reads every watched page, which can take up to about 25 minutes. New
and changed pages go through Knowledge and show up in Review. 409
refresh_in_progress while a refresh is queued or running, refresh_recent
within an hour after the last refresh finished, website_refresh_off while
the website refresh is not on, no_website when the workspace has no
website. Needs a workspace admin.
writing-style-relearn
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/writing-style/relearn
Ask Ken to learn your writing style from your sent mail again ("Relearn").
POST /api/v1/knowledge/writing-style/relearn. Needs the knowledge flag.
Returns 202 {queued: true} at once. On the next hourly run, Ken reads the
newest sent 1:1 emails (at most 50) of the user who connected the agent,
through their own Gmail or Outlook Knowledge source. It keeps only how
they write, never what they said. It files the new rules as one private
suggestion on their You / Writing style file, labelled "Learned from N of
your sent emails". It never relearns another member. 409 no_mailbox_ingest
when the user has no Gmail or Outlook source of their own with ingest on,
ingestion_off while Ken reads no mailbox for Knowledge in the workspace.
Needs Knowledge edit.
website-pages-replace
Write. Early access: needs knowledge on for the workspace. PUT https://api.ken.so/v1/knowledge/website/pages
Body (json): urls array
Replace the list of pages Ken watches on the workspace's website (at most 15).
PUT /api/v1/knowledge/website/pages with {urls}. Needs the knowledge flag.
Send the whole list: URLs of the workspace's website, or paths such as
"/pricing". A page left out stops being read, and its pending suggestions
are removed from Review. Facts already approved from it stay, because the
page is public, and nightly cleanup ages them out. Ken never adds a
removed page back on its own; a page of a previous website is retired
instead, so Ken may pick it again if the workspace moves back. Adding or
removing pages needs a workspace admin. Returns the list as
website-pages-list does. 400 invalid_url names the URL that is not a page
of the website; 409 no_website when the workspace has no website.
versions-restore
Write. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/files/{fileId}/versions/{version}/restore
Path: fileId, version
Body (json): baseVersion integer
Restore an older version of a Knowledge file. It becomes a new version; nothing is lost.
POST /api/v1/knowledge/files/{fileId}/versions/{version}/restore. Needs the knowledge flag.
Sends Ken-Version 1.1. version is the one to bring back (from versions-list); base_version is
the file's current version (from get); a stale one is version_conflict. Copies that version's
name, body and tags into a new version and returns it.
search
Read. Early access: needs knowledge on for the workspace. POST https://api.ken.so/v1/knowledge/search
Body (json): accountId integer, includeEvidence boolean, kinds array, limit integer, observedAfter date-time, observedBefore date-time, personId integer, q string
Search Knowledge facts and source text for what the context pack does not cover. Call context first.
POST /api/v1/knowledge/search with {q, accountId?, personId?, kinds?,
observedAfter?, observedBefore?, limit?, includeEvidence?}.
Needs the knowledge flag. Hybrid search (vector and full text, fused by
rank, reranked) over the facts and source text you can see, for questions the
pack does not answer ("what did Dana say about security?"). kinds narrows
to fact kinds (pain, objection, priority, next_step, commitment, pricing,
stack, competitor, relationship, role, event, preference, product, proof,
style) and returns facts only. observed_after (inclusive) and
observed_before (exclusive) are ISO 8601 times. limit is 1 to 50, default
10; include_evidence defaults to true. Returns {data: [{citationId, type
(fact or evidence), text, kind, sourceType, sourceLabel, sourceUrl,
observedAt, accountId, personId, score, stale}], pagination: {hasMore:
false}}. sourceUrl is set only for a source with no owner or one you own.
An unknown account_id or person_id is 404 account_not_found or
person_not_found. This read changes nothing.
update
Write. Early access: needs knowledge on for the workspace. PATCH https://api.ken.so/v1/knowledge/files/{fileId}
Path: fileId
Body (json): active boolean, baseVersion integer, body string, cmd string, description string, folderId integer, name string, reason string, section object, status string, tags array, trigger string, visibility string
Change a Knowledge file: its whole body or one section, its name, tags, status or folder. base_version (the version from get) is required; a stale one is version_conflict, so get again.
PATCH /api/v1/knowledge/files/{fileId}. Needs the knowledge flag. Sends Ken-Version 1.1. Send
body (the whole markdown) or section {"heading": "Pains", "body": "..."} (one heading's content;
an empty body clears it; a heading the file lacks is appended), not both. Other fields: name,
tags (replaces the list; [] clears it), status (ok or off), folder_id (moves the file within its
section), active, cmd and trigger (an empty string clears either one), visibility, and reason
(why, shown in history). visibility applies to skills and instructions only: workspace shares
the file with everyone in the workspace, so Ken's drafts for every member follow it (admins
only; anyone else gets 403 permission_denied), and private makes it yours alone. Every save
writes a version labelled "<user> via <client>" and returns the file with its new version. A
file you cannot change is 403 forbidden: propose the change with suggestion-create instead.