Knowledge base
The knowledge base holds your workspace's reference documents. Create, edit, organize and delete documents, add a website or pages from a connected tool, have AI regenerate a system document, and link a document to the applications and features it describes. Search it or ask it a question, review changes the AI proposes, and browse or restore a document's earlier versions. See Knowledge base.
List the knowledge-base tag vocabulary
The distinct tags in use across the workspace's knowledge-base documents, with how many documents carry each. These names are what knowledge-base search filters match (the search tool's tags argument and an agent's kbFilters), so choose filter values from this vocabulary — and prefer an existing name over minting a near-duplicate when tagging.
path Parameters
workspaceIdWorkspace UUID
List the knowledge-base tag vocabulary › Responses
Tag names with document counts, alphabetical
Check what knowledge base indexing would start on its own
Answers what indexing a new source (an upload, a website, an imported or generated document) would start on its own in this workspace, all on the organization's AI credits: the Overview is redrafted when it was never generated, or was generated and never edited (overviewRefresh), and, in a workspace with no features yet, indexing that Overview drafts starter features and writes a specification for each (starterFeatures). estimate is a measured estimate of what a newly indexed source would start, in AI credits and in cents at the plan's price (null when the plan sets no AI credit price); 0 when nothing would run. Nothing runs and nothing is charged.
path Parameters
workspaceIdWorkspace UUID
Check what knowledge base indexing would start on its own › Responses
What indexing would start on its own, and its estimate
List knowledge base documents in a workspace
Returns all editable documents in the workspace knowledge base — system docs (overview, personas, …) plus user-uploaded files, scraped websites, connector imports, and manual documents. Does not include the contentLexical payload; use get-kb-document for full content.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
searchFull-text search across searchable fields
List knowledge base documents in a workspace › Responses
List of KB documents
Create a new knowledge base document
Creates a KB document. Without content it is an empty manual document the user edits in the app. With content (full markdown) the server derives the editable state, snapshots version 1, and marks the document as generated: use this for agent-produced documentation. parentDocumentId nests the document in the KB tree (system documents cannot be parents); applicationId auto-links it to that application; availableToAgents: true indexes it for agent search, on the organization's AI credits; when the organization cannot pay for indexing now, the document is still created and shared, and waits to be indexed (metadata.indexDeferred) until it can. Indexing can start more work on its own, also on AI credits: an Overview that was never generated, or was generated and never edited, is redrafted from the new content, and in a workspace with no features yet, indexing the Overview drafts starter features and writes a specification for each. To CHANGE an existing document's content, use propose-kb-document-content, never create a duplicate.
path Parameters
workspaceIdWorkspace UUID
Create a new knowledge base document › Request Body
titledescriptioncontentOptional initial markdown body. When set, the server derives the editable Lexical/Y.Doc state, snapshots version 1, and marks the document as generated.
parentDocumentIdOptional parent KB document id — creates this document as a child node in the document tree. System documents cannot be parents or children.
applicationIdOptional application id to auto-link this document to (kb_document documents application).
availableToAgentsShare the document with agents (chunk + embed) once content is saved. Defaults to false; only meaningful together with content.
tagsOptional content-domain tags — product (specs, overviews, personas, UX), engineering (technical documentation), research (interviews, competitor/market research). Agents filter KB search on this axis. When omitted, a document created with content defaults to ["engineering"]; providing the field (even an empty array) is honored exactly.
Create a new knowledge base document › Responses
Document created
Delete multiple knowledge base documents in one request
Deletes every document in ids. Cascade-aware: selecting a parent plus some of its descendants only fires the parent delete — the subtree is removed once, not twice. System documents inside the selection are rejected with a 400.
path Parameters
workspaceIdWorkspace UUID
Delete multiple knowledge base documents in one request › Request Body
idsDelete multiple knowledge base documents in one request › Responses
Documents deleted
Reorder a KB document among its siblings and/or re-parent it
sortOrder is the 0-based target position among siblings; parentDocumentId: null moves the document to the root level. System documents cannot be nested or become parents. UI drag-and-drop only.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Reorder a KB document among its siblings and/or re-parent it › Responses
Document reordered
List the applications/features a KB document is linked to
Returns the entities this document documents (kb_document → application|feature links), with display names and the per-link last-scanned commit baseline.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
List the applications/features a KB document is linked to › Responses
Links for the document
Link a KB document to an application or feature
Creates a documents relationship from the KB document to the named application or feature (idempotent — re-linking an existing pair is a no-op). Linked documentation surfaces on the target's Documentation rail and grounds coding sessions that run against the application.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Link a KB document to an application or feature › Request Body
entityTypeTarget entity type
entityIdTarget entity UUID (application or feature id)
Link a KB document to an application or feature › Responses
Updated links for the document
List content proposals for a KB document
Agent-drafted content rewrites awaiting review (or settled history). Pass ?activeOnly=true for the single pending proposal.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
query Parameters
statusFilter by status
activeOnlyOnly the active proposal, if any
List content proposals for a KB document › Responses
Proposals
Propose a full content rewrite for an existing KB document
Submits the FULL replacement markdown for an EXISTING knowledge base document as a proposal a human reviews (rendered block diff) before it lands — use this instead of update-kb-document or any direct write for every agent-driven content change. Include the sessionId from your Context section. Returns 409 if a proposal is already pending for the document — skip it and mention that in your report notes.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Propose a full content rewrite for an existing KB document › Request Body
proposedContentMarkdownThe FULL replacement markdown for the document. Code citations are link tokens — path/to/file.ext:line @
summaryOne-paragraph summary of what changed and why
sessionIdThe session id (from the Context section of your instructions)
commentIdWhen you answer a comment thread on this document (your turn input names it): the thread's id, exactly as given. The suggestion is then linked to the thread, and applying it resolves the thread. Only the thread you were asked to answer, while you answer it; omit it otherwise.
Propose a full content rewrite for an existing KB document › Responses
Proposal created (awaiting review)
Approve a proposal without applying it (PR-rail review)
Freezes the human-composed markdown; the PR-merge webhook applies it when the code PR merges. Human review surface only.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
proposalIdProposal UUID
Approve a proposal without applying it (PR-rail review) › Request Body
contentdraftVersionApprove a proposal without applying it (PR-rail review) › Responses
Proposal approved
Apply the composed markdown of a proposal to the document
Writes the reviewer-composed markdown through the versioned save-content path (pre-apply snapshot = restore point), settles the proposal, and stamps scan baselines. Human review surface only.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
proposalIdProposal UUID
Apply the composed markdown of a proposal to the document › Request Body
contentdraftVersionApply the composed markdown of a proposal to the document › Responses
Proposal applied
Dismiss a proposal wholesale
The scan baseline is NOT advanced. Human review surface only.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
proposalIdProposal UUID
Dismiss a proposal wholesale › Responses
Proposal dismissed
List the knowledge base proposals awaiting review
The workspace's proposed changes to its knowledge base that are waiting for someone to review them: rewrites of existing documents and new documents alike, newest first. Each row names what the proposal targets and where it came from; open the proposal to see its content.
path Parameters
workspaceIdWorkspace UUID
query Parameters
statusWhich proposals: awaiting_review, the ones waiting for someone to review them.
forMetrue: only the proposals drafted by a session FOR the caller (assigned to them, started by them, or in the view of a team they are on), the sidebar's Knowledge base count. Default false: every proposal.
pagePage number, from 1 (default 1)
limitProposals per page, at most 100 (default 50)
List the knowledge base proposals awaiting review › Responses
Proposals awaiting review
Propose a NEW knowledge base document for an application
Use this when an application in your session Context has NO technical documentation (hasTechnicalDocs: false), or its documentation tree is missing a section — it proposes a document that does not exist yet. Nothing is created now: the proposal is reviewed by a human in the session's PR activity rail, and the document is created and linked to the application when the code PR merges. Returns the proposal; its id is what a child section passes as parentProposalId to nest under a root you proposed in the same session (propose the root FIRST). Include the sessionId from your Context section. Never use create-kb-document for documentation a human should review first. Returns 409 when a creation with this title is already pending for the application — skip it and mention that in your report notes.
path Parameters
workspaceIdWorkspace UUID
Propose a NEW knowledge base document for an application › Request Body
titleThe title the document will be created with. The root of an application's technical documentation is "
proposedContentMarkdownThe FULL markdown of the new document. Code citations are link tokens — path/to/file.ext:line @
applicationIdThe Application this document documents (its id from the Context). The created document is linked to it.
parentDocumentIdAn EXISTING document to nest the new one under. Omit for a root document. Use parentProposalId instead when the parent is another creation you proposed in this same session.
parentProposalIdThe id returned by an earlier propose-kb-document-creation call in this session whose document the new one nests under — how a child is attached beneath a root that does not exist yet. Resolved when both are applied; a dismissed parent puts the child at root.
summaryOne paragraph: why this document is needed and which changed files motivated it
sessionIdThe session id (from the Context section of your instructions)
Propose a NEW knowledge base document for an application › Responses
Creation proposal recorded (awaiting review)
Approve a document-creation proposal without applying it (PR-rail review)
Freezes the human-composed markdown; the PR-merge webhook creates and links the document when the code PR merges. Human review surface only.
path Parameters
workspaceIdWorkspace UUID
proposalIdProposal UUID
Approve a document-creation proposal without applying it (PR-rail review) › Request Body
contentdraftVersionApprove a document-creation proposal without applying it (PR-rail review) › Responses
Proposal approved
Dismiss a proposal wholesale, by proposal id
The proposal-scoped dismiss — either kind; the one route a creation proposal (which has no document) can be dismissed through. Human review surface only.
path Parameters
workspaceIdWorkspace UUID
proposalIdProposal UUID
Dismiss a proposal wholesale, by proposal id › Responses
Proposal dismissed
Remove a KB document ↔ entity link
Idempotent — removing an absent link is a no-op.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
entityTypeLink target type: application | feature
entityIdTarget entity UUID
Remove a KB document ↔ entity link › Responses
Updated links for the document
Get a knowledge base document by ID
Retrieve a single KB document with its markdown content and metadata. The heavy contentLexical CRDT payload is omitted by default; pass ?includeLexical=true if you are the collaborative editor and need to bootstrap.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
query Parameters
includeLexicalOpt in to receive the Lexical CRDT payload alongside markdown. Defaults to false — only the collaborative editor needs it.
Get a knowledge base document by ID › Responses
KB document details
Update a KB document's metadata (title, tags, description)
Renames a document, or changes its tags or description. The title is trimmed and must be 1 to 255 characters; sending the current title changes nothing. A rename is refused with 409 for a system document (Overview, Personas, User experience and Competitors keep their names), when another document in the workspace already has exactly that title, and for a document synced from a repository (change its title in the repository instead). Search results show the new name straight away. The document's content is edited in the document editor, not through this endpoint.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Update a KB document's metadata (title, tags, description) › Request Body
titleRename the document. Trimmed, then 1 to 255 characters. Refused with 409: on a system document (Overview, Personas, User experience, Competitors keep their names; kb_document_title_fixed), when another document in the workspace already has exactly this title (kb_document_title_taken), and on a document synced from a repository (change its title in the repository; kb_document_repository_synced).
tagsdescriptionUpdate a KB document's metadata (title, tags, description) › Responses
Updated document
Get a system knowledge base document by its stable type slug
Returns a single system document addressable by stable type slug (e.g. overview, personas). Only system documents are addressable this way — manual / imported documents are reachable only via search. Returns markdown content plus metadata; the heavy contentLexical CRDT payload is omitted unless ?includeLexical=true is passed.
path Parameters
workspaceIdWorkspace UUID
typeStable kebab-case slug — e.g. overview, user-experience, personas.
query Parameters
includeLexicalOpt in to receive the Lexical CRDT payload alongside markdown. Defaults to false — only the collaborative editor needs it.
Get a system knowledge base document by its stable type slug › Responses
KB document details
Trigger AI generation for a wired system document (async)
Starts AI generation of a wired system document (the Overview, User experience or Personas) in the background, on the organization's AI credits, and returns 202 at once with the document in its current state. Wait for a doc:persisted frame on this documentId on the workspace WebSocket, then read the document again. The generated document is indexed for agent search when it lands. Indexing can start more work on its own, also on AI credits: an Overview that was never generated, or was generated and never edited, is redrafted from the new content, and in a workspace with no features yet, indexing the Overview drafts starter features and writes a specification for each.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Trigger AI generation for a wired system document (async) › Responses
Generation task accepted; result will arrive over the WebSocket
Save KB document content from a non-collaborative editor
Writes a markdown body to the KB document, rebuilds the Y.Doc binary, broadcasts doc:reset to any open CollabEditor on the same room, and emits doc:persisted so KB document queries refetch. Used by single-user surfaces that edit outside the CollabEditor.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
Save KB document content from a non-collaborative editor › Responses
Saved document
Search the knowledge base using semantic search
Perform vector similarity search across all indexed documents in the workspace. Returns matching text chunks ranked by relevance.
path Parameters
workspaceIdWorkspace UUID
Search the knowledge base using semantic search › Request Body
querymodelimittagsexcludeTagsSearch the knowledge base using semantic search › Responses
Search results
Query knowledge base with RAG
Ask a question and get an AI-generated answer grounded in the workspace's knowledge base documents.
path Parameters
workspaceIdWorkspace UUID
Query knowledge base with RAG › Request Body
questionpromptTemplatemodelimittagsQuery knowledge base with RAG › Responses
RAG response with answer and sources
Scrape a website and add it to the knowledge base
Starts an asynchronous scrape of a website into a new knowledge base document; read the document with get-kb-document to follow its progress. With makeAvailableToAgents (the default) the pages are indexed for agent search on the organization's AI credits. Indexing can start more work on its own, also on AI credits: an Overview that was never generated, or was generated and never edited, is redrafted from the new content, and in a workspace with no features yet, indexing the Overview drafts starter features and writes a specification for each. When the organization cannot pay for indexing now, the site is still scraped, stored and shared, and indexing says it waits: it is indexed with no further action once the organization can pay.
path Parameters
workspaceIdWorkspace UUID
Scrape a website and add it to the knowledge base › Request Body
urlmaxPagesmaxDepthchunkingStrategysummarizetagsOptional tags for the scraped document — free-form names, applied as user tags
makeAvailableToAgentsScrape a website and add it to the knowledge base › Responses
Scrape task created
Ingest documents from a connected integration into the knowledge base
Starts a workforce workflow that fetches the selected items from a source connector, converts them to markdown, and pushes the content into the knowledge base via the ingest-text-document callback.
path Parameters
workspaceIdWorkspace UUID
Ingest documents from a connected integration into the knowledge base › Request Body
connectorInstanceIdproviderIngest documents from a connected integration into the knowledge base › Responses
Workflow execution queued
Create a knowledge base document from raw text content
Invoked by the workforce productmind.workspace.ingest_text_document action after it has fetched and converted a document.
path Parameters
workspaceIdWorkspace UUID
Create a knowledge base document from raw text content › Request Body
namecontentchunkingStrategyuserIdIgnored. The document is attributed to the person the request acts as, never to a person this field names.
Create a knowledge base document from raw text content › Responses
Document created and indexing queued
List version history for a knowledge base document
Returns every persisted snapshot of a KB document, newest first. Use this to inspect prior content, attribute changes to specific authors, or pick a version to restore.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
query Parameters
documentIdKnowledge base document UUID
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
searchFull-text search across searchable fields
List version history for a knowledge base document › Responses
List of KB document versions
Get a single KB document version
Fetch one historical version including its Lexical JSON state and the markdown projection. Useful for diff-rendering a snapshot or previewing before restore.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
versionIdVersion UUID
Get a single KB document version › Responses
KB document version detail
Name a KB document version
Attach (or clear) a human-readable summary so the version surfaces nicely in the history panel.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
versionIdVersion UUID
Name a KB document version › Responses
Renamed KB document version
Restore a KB document to a historical version
Roll a KB document back to a prior version. Creates a new snapshot mirroring the chosen version, writes it to the live document, broadcasts doc:reset so any open editor reloads, and flips the document's isStale flag so the user is prompted to reindex.
path Parameters
workspaceIdWorkspace UUID
documentIdKB document UUID
versionIdVersion UUID
Restore a KB document to a historical version › Responses
Restored KB document