SANDI Solr

1Overview

Module map

AI service map

Request flow

2Common Conventions

Required fields on every request

Standard response envelope

HTTP status codes

Base URLs

3Search API

The Search API exposes one logical operation — execute a search — available as both POST (JSON body) and GET (query parameters).

Accepts a JSON body. Preferred for complex queries with many optional flags.

Same parameters as POST but passed as query string. Suitable for simple queries and browser testing.

Request fields

Response fields

Example — hybrid search with reranking and RAG

Example — GET search with filter

Precision level reference

4Index API

Accepts an array of JSON documents and immediately indexes them into the client's Solr collection. Each document is chunked, embedded, and written to Solr in a single synchronous call. For large bulk imports use the Schedule API instead.

Request fields

Response fields

Document ID resolution

SANDI resolves a unique document ID in this order:

1. The value of the id field in the document, if present
2. The value of the uri field, if present
3. A generated UUID — used when neither id nor uri is provided

Example

5Delete API

Deletes one or more documents from the client's Solr collection. Three deletion modes can be used simultaneously in a single request.

Request fields

Response fields

Examples

Delete by single ID

Delete by multiple IDs

Delete by query

Combined (all three modes in one call)

6Schedule API

The Schedule API manages background indexing jobs. Jobs are stored in memory and checked every second by IndexingJobScheduler. When a job's scheduledTime is reached it is executed asynchronously.

Create and schedule a new indexing job.

Request fields

Response fields

Job type reference

Job status lifecycle

Schedule job example

Returns all jobs (scheduled, running, completed, failed, cancelled) as an array of IndexingJob objects.

IndexingJob object fields

Returns a single IndexingJob object. Returns 404 if the job does not exist.

Returns all jobs with the given status. Valid values: SCHEDULED, RUNNING, COMPLETED, FAILED, CANCELLED (case-insensitive). Returns 400 for an unrecognised status value.

Cancels a scheduled job. Returns 400 if the job is not found or is not in SCHEDULED state.

Returns a simple counts object.

7Admin API

The Admin API manages tenants (clients), Solr collections, Solr configurations, and synonym sets. All endpoints require a requestId query parameter.

Client management

Returns an array of all client objects.

Returns a single client object. Returns 404 if not found.

Creates or updates a client. If createCollection is true, a new Solr collection is created using the named configuration set before the client record is saved.

Request body (ClientRequest)

Create client example

Deletes the client record. Does not delete the associated Solr collection. Returns 404 if not found.

Collection management

Returns a list of all Solr collection names.

Returns a Collection object: { "name": "acme_docs", "configuration": "sandi_config" }.

Creates a new Solr collection. Request body: { "name": "my_collection", "configuration": "sandi_config" }

Updates the configuration set linked to an existing collection. The name in the path and body must match.

Deletes the Solr collection and all its data. Returns 404 if not found.

Configuration management

Solr configurations (config sets) are stored in the directory specified by sandi.collections.config. These endpoints upload them to ZooKeeper so SolrCloud can use them when creating collections.

Returns a list of all available configuration set names.

Uploads the named configuration set from the local file system to ZooKeeper.

Deletes the named configuration set from ZooKeeper. Returns 404 if not found.

Synonym management

Synonym sets are uploaded to SolrCloud via ZooKeeper and referenced by name in the client's synonyms array.

Returns a list of all synonym set names available in ZooKeeper.

Uploads a synonym file to ZooKeeper.

Deletes the named synonym set from ZooKeeper. Returns 404 if not found.

8Document Indexing Pipeline

Every document submitted to POST /index or processed by a scheduled job passes through the following steps:

9Search Query Pipeline

When a search request is received the following steps are executed, each step conditional on the corresponding request flag:

10AI Service HTTP Contracts

Each AI service is a lightweight Python/Flask microservice. SANDI calls them over HTTP; the interface contract below is what SANDI expects, regardless of whether the service is backed by a local GPU model or a cloud API.

Embedding service (emb) · default port 8085

Converts one or more text strings into dense float vectors. Called during indexing (per chunk) and during search (per query).

Computes cosine similarity between two texts. Used internally for relevance checks.

NLP service (nlp) · default port 8086

Runs SpaCy NLP analysis on the input text. Returns entities, part-of-speech tags, and lemmatized tokens. Used by the search pipeline to understand query intent.

LLM service (llm) · default port 8087

Sends a prompt to the language model and returns generated text. Used for spell check, query expansion, and RAG answer generation. The caller constructs the full prompt; the service returns the raw model output.

Reranking service (rer) · default port 8088

Accepts a query and a list of document text snippets. Returns a relevance score for each document computed by a cross-encoder model. SANDI uses these scores to reorder the search result page.

Scores are in the same order as the input docs array. SANDI sorts the result page by descending score after receiving the response.

11Client Model Reference

The client record is the central configuration object for a tenant. It is stored as a Solr document in the internal _clients collection and loaded at request time for every search and index operation.