Knowledge Base API Guide

The Knowledge Base API stores documentation as spaces of hierarchical, versioned pages, imports documents into them, tracks entities across them, and supports reviewed authoring with an agent. Swagger is the contract; this guide is the map.

Spaces

A space is a top-level container of pages for the current project, addressed by slug. Create, list, get and delete are available; only custom spaces can be deleted.

Content-sourcing mode is fixed when the space is created. OWNED (the default) means Xema stores both authored and mirrored page bodies. FEDERATED means the external documentation provider, reached through the org's documentation connection, stays the source of truth: Xema keeps only index metadata and reads bodies live, and the slug must match the provider's space key so provider events link up. An OWNED space can be contracted to FEDERATED once. That drops the page bodies Xema mirrored and their stored version history, and the response reports how many pages and versions were affected.
Data classification is declared on the space as a floor for every page in it. A page may raise its classification but never lower it.
Spaces, like other resources, support per-resource shares: list the shares of a resource, grant a subject exactly one share level, or remove it.

Pages

A page has a slug (lowercase letters, digits and hyphens, a single path segment), a title, Markdown content and an optional parent. Hierarchy comes from parentId, never from slashes in the slug. A content type of folder makes a container-only node. Pages can also carry a free-form label map.

Task	Call
Create, list, fetch by slug or id	`POST` and `GET /spaces/{spaceSlug}/pages`, `GET /pages/{pageId}`
Page tree of a space	`GET /spaces/{spaceSlug}/pages/tree`
Update (creates a new version)	`PUT /spaces/{spaceSlug}/pages/{pageId}`
Move pages to a new parent or the root	`PATCH /spaces/{spaceSlug}/pages/move`
Bulk upsert by slug	`POST /spaces/{spaceSlug}/pages/bulk`
Search across spaces	`GET /pages/search` (`q`, `limit`, `sourceType`; with no `q` it lists recent pages)
History and revert	`GET .../pages/{pageId}/versions`, `GET .../versions/{version}`, `POST /pages/{id}/revert`
Import an agent session file as a page or a new revision	`POST /spaces/{spaceSlug}/pages/import-from-session`

Every update creates a new version, and a revert creates another new version rather than rewriting history, so the audit trail stays intact. Bulk upsert reports per page whether it was created, updated, failed, conflict or skipped; a conflict returns the current content hash so you can reconcile.

Proposals

An agent's edit to a human-authored page is not published straight away. It becomes a proposal. GET /proposals lists the pending ones, and POST /proposals/{pageId}/approve publishes the change while .../reject reverts to the previous version.

Ingestion

Ingestion imports existing files as pages.

Optionally read the upload limits: GET /ingestion/upload/config returns the maximum file size, the maximum number of active jobs per organization and the accepted formats, MIME types and extensions.
Upload a file with POST /ingestion/upload, or create a job with POST /ingestion/jobs, giving the target spaceSlug, a format (MARKDOWN_ARCHIVE, PDF, DOCX, PLAIN_TEXT or MARKDOWN_FILE) and optionally a parentPageId so imported pages land under a folder.
Poll GET /ingestion/jobs/{id}, list jobs, or cancel one. For an uploaded file you can fetch a preview URL or download the original.

Jobs run asynchronously.

Knowledge graph

GET /knowledge-graph queries the graph by entity name and GET /knowledge-graph/entities lists the entities Xema extracted from your pages. GET /connection/freshness reports how fresh the documentation connection's data is.

The Documents console

In the web app, Documents (Knowledge menu, per project) is one place to read and edit a project's written output: knowledge-base pages and proposals, architecture artifacts, and documents produced by workflow runs. Each opens in place with its version history. The console lives at /projects/<projectId>/documents; a settings page for document authoring sits at .../documents/settings, and a page opens at .../documents/<spaceSlug>/<pageSlug>. Pages offer comment and change rails and a PDF export. The console needs the knowledge-base biome and shows nothing for an organization where it is disabled.

Authoring documents with an agent

Documents created for authoring come in two kinds: MARKDOWN_DOCUMENT (Markdown source, reviewed change by change) and RICH_DOCUMENT (rendered HTML with comments anchored to text). POST /spaces/{spaceSlug}/documents creates one with no session, and POST /document-sessions creates the page and opens its authoring session in one call.

When an agent changes a document, the changes wait for your review:

GET /pages/{pageId}/pending-patches lists each reviewable change, in application order. A change is PENDING, ACCEPTED, REJECTED or STALE.
Accept one change or reject one (rejecting restores the baseline text for exactly that hunk, and you can leave a comment saying why, which the agent sees).
POST /pages/{pageId}/review/accept accepts all unreviewed changes at once, and .../review/undo reverts all of them. Both are idempotent.
If the live authoring session did not follow a decision, POST /pages/{pageId}/session-resync re-materializes its working files; retry that, not the decision.
Comments (OPEN, RESOLVED or STALE) are listed, added with threaded replies, and resolved under /pages/{pageId}/comments.

Previous: ← Activity Feed Realtime Frames Next: Project Registry API Guide →