RAG Service API

Overview

Optional hybrid search service for AST-rendered DITA content. Chunks each topic along heading boundaries, embeds the chunks with a local model chosen at image build time (EMBED_MODEL), and ranks results by fusing embedding similarity with BM25.

mcp-server delegates search_documentation to this service when RAG_SERVICE_URL is set, and falls back to MiniSearch on any non-OK or empty response.

Startup: the service accepts connections immediately, but POST /api/search returns 503 until the first indexing pass completes.

Index freshness: data-store calls POST /api/reindex after doc set uploads and deletes when its own RAG_SERVICE_URL is set. Reindexing is incremental (SHA-256 per topic).

Version information

Version: 1.0.0

URI scheme

Host: {scheme}://{host}:{port}

RAG Service - System

RAG service health and readiness

Responses

HTTP CodeDescriptionSchema
200 Server is running object

Produces

  • application/json

RAG Service - Indexing

Keep the RAG index in step with the data store

Scans the data directory, re-embeds topics whose content hash changed, and purges topics that are no longer listed in their doc set's toc.json. Calls are serialised, and the response is sent when the pass finishes, which can take minutes for large uploads.

Responses

HTTP CodeDescriptionSchema
200 Reindex complete object
500 Reindex failed RagError

Produces

  • application/json

Definitions

NameDescriptionSchema

id
optional

Doc set ID and topic path, or the bare topic path for the default set
Example: dita-ot-docs/topics/plugins-removing

 string

docId
optional


Example: dita-ot-docs

 string

topicPath
optional


Example: topics/plugins-removing

 string

title
optional

 string

shortdesc
optional

 string

lang
optional


Example: en

 string

sectionTitle
optional

 Heading of the best matching chunk; omitted when it equals the topic title string

anchor
optional

Slug of sectionTitle
Example: removing-plug-ins

 string

snippet
optional

 First 250 characters of the best matching chunk string

score
optional

Fused relevance from 0 to 10, comparable only within one response
Example: 9.3

 number

NameDescriptionSchema

error
optional

 Message, or the field-level validation tree for 400 object