Search and Rendering Guide

This guide covers two APIs that work on content other APIs own: search-api, which finds it, and document-render-api, which turns it into a downloadable file.

Search

Search runs across the content a project and organization have, from every installed biome that contributes to the index. Indexing is event-driven, so a biome's documents appear after it publishes them rather than on a schedule. Xema does not need a separate search cluster. A distribution that does not install the search biome still runs; it just has less discovery.

Querying

GET /search takes:

Parameter	What it does
`query`	The search text.
`searchMode`	`text` (keyword ranking), `semantic` (meaning-based ranking over embeddings) or `hybrid` (both, merged with reciprocal-rank fusion). Pick `text` for exact terms and identifiers, `semantic` for natural-language questions, and `hybrid` when you want both.
`docTypes`, `tags`, `phase`	Filters.
`fuzziness`	How much typo tolerance to apply.
`expandQuery`	Adds related terms to the query.
`facets`	Includes aggregations (document type, tags, phase, date) in the same response.
`limit`, `offset`	Pagination.

A hit carries the document id, a relevance score, the docType, the organization and project, the source entity id and a ref to the object. The response also has the total count.

docType is an open set. Every installed biome can contribute its own result types, so treat it as a string and discover the current set with GET /search-types (or the search:types.list@1 capability). Each type declares where its results open; GET /search-types/resolve-route?ref=<xema:// ref> returns the frontend URL for a reference.

GET /search/facets returns only the aggregations, optionally narrowed by a query q, and nested=true adds sub-aggregations such as phases per document type.

Operating it

POST /admin/reindex starts a full reindex for the organization, and GET /admin/reindex/{jobId} reports progress.
GET /traces lists recent searches and GET /traces/stats gives counts and average latency by mode (TEXT, SEMANTIC, HYBRID). Both take sinceDays.

The Search console

The Search page in the web app queries knowledge-base pages, backlog items and artifacts from one box. You choose keyword, semantic or hybrid ranking (hybrid is the default), and results are fetched when you submit. After a query the page offers the document-type facets the index reports for the query, to narrow the results. Errors appear as an error card, never as an empty list.

Rendering documents

The Document Render API produces a file from a source. Use it for knowledge-base pages, reports and workflow deliverables.

POST /renders with a source, a format (PDF or DOCX) and an optional idempotencyKey (up to 200 characters). A repeat with the same key returns the existing record instead of rendering again.
The source is either a knowledge-base page (kind: PAGE, with spaceSlug, pageSlug and an optional pinned version, otherwise the latest published) or inline HTML (kind: INLINE_HTML, up to 2,000,000 characters, with an optional title for the file metadata). You can also pass a design-system binding to apply a brand; with none, nothing is applied.
The call blocks until the render finishes and returns a record with status, byteSize and a downloadUrl. Statuses are QUEUED, RUNNING, READY, FAILED and CANCELLED, and a failure carries a failureReason.
GET /renders/{id} re-reads a record, and GET /renders/{id}/download streams the file. Download answers 404 until the record is READY.

Previous: ← Project Registry API Guide