Search API — Full-Text and Metadata Document Search

QualityDocD provides a dual-engine search layer that spans two data stores. MongoDB’s document_metadata collection powers relevance-ranked full-text and regex content search, while the PostgreSQL search_index table provides a token-based fallback that remains available even when MongoDB is unreachable. The three search endpoints cover broad document discovery (GET /search), fast title autocomplete (GET /search/suggest), and manual re-indexing (POST /search/index). All search results are company-scoped: non-SUPER_ADMIN users only see documents that belong to their own company, both in MongoDB filters and in PostgreSQL queries.

GET /search

Searches indexed documents using one of three modes. An empty q returns all indexed documents visible to the user. Auth: Bearer token
Module access: MODULE_2 — VIEWER, COMMENTER, CONTRIBUTOR, OPERATOR, COMPANY_ADMIN, SUPER_ADMIN

Query parameters

string

The search query string. An empty or omitted q returns all indexed documents without filtering.

mode

"metadata" | "content" | "all"

Controls which search engines are used. Defaults to "all".

"metadata" — MongoDB $text search on title and contentText; falls back to PostgreSQL token matching if MongoDB is unavailable.
"content" — MongoDB regex search specifically on the contentText field.
"all" — Runs both metadata and content searches, then deduplicates results by documentId.

field

"title" | "body" | "all"

Restricts which token arrays are matched during the PostgreSQL fallback. Defaults to "all". Has no effect when MongoDB handles the query.

"title" — only matches tokens in titleTokens
"body" — only matches tokens in bodyTokens
"all" — matches tokens in either array

Use mode=metadata for the fastest searches. MongoDB’s $text index uses a pre-built inverted index with relevance scoring, making it significantly faster than regex content scans or PostgreSQL token matching for large document sets.

How search works

metadata mode
content mode
all mode (default)

When mode=metadata (or mode=all) and q is non-empty, the API first attempts a MongoDB $text search across the document_metadata collection. Results are ranked by text relevance score and limited to 30 documents.If MongoDB is unavailable or throws an error, the API automatically falls back to the PostgreSQL search_index table. It tokenizes the query using the same tokenizer used during indexing (lowercase, accent-normalized, stop words stripped) and checks each indexed entry’s titleTokens and bodyTokens arrays for overlap. The field query parameter controls which arrays are checked.

curl -G https://api.qualitydocd.example/api/search \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "q=política de calidad" \
  --data-urlencode "mode=metadata"

Results carry source: "mongodb-metadata" (MongoDB) or source: "postgres-index" (PostgreSQL fallback).

When mode=content, the API performs a case-insensitive MongoDB regex match ($regex, $options: "i") against the contentText field. This is useful for locating specific phrases or clause text within document bodies.Results are limited to 30 documents and deduplicated against any metadata results already collected (in mode=all).

curl -G https://api.qualitydocd.example/api/search \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "q=auditoría externa" \
  --data-urlencode "mode=content"

Results carry source: "mongodb-content".

When mode=all, the API runs both the metadata search and the content search in sequence and merges the results. Deduplication happens by documentId — if a document appears in both result sets, the matchedIn field of the first match is updated to "metadata+content" rather than adding a duplicate entry.

curl -G https://api.qualitydocd.example/api/search \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "q=ISO 9001" \
  --data-urlencode "mode=all"

Response

query

string | null

The search query that was used, or null if none was provided.

mode

string

The mode that was applied: "metadata", "content", or "all".

total

integer

Total number of results returned after deduplication.

results

array

Array of matching document version result objects.

Show result item fields

source

"mongodb-metadata" | "postgres-index" | "mongodb-content"

Which search engine produced this result.

documentId

integer

ID of the matching document.

versionId

integer

ID of the specific version that matched.

title

string

Title of the document.

versionNumber

string

Version string of the matched version, e.g. "2.0".

contentUrl

string | null

URL to the document file, or null if not stored (MongoDB-sourced results always return null here; PostgreSQL results include the stored URL).

matchedIn

Describes where the match was found. PostgreSQL fallback results use "title", "body", or "both". MongoDB results use "metadata", "content", or "metadata+content".

snippet

string

A short excerpt of the contentText surrounding the query match, up to 80 characters of context with … added at truncation boundaries.

Example response

{
  "query": "ISO 9001",
  "mode": "all",
  "total": 2,
  "results": [
    {
      "source": "mongodb-metadata",
      "documentId": 12,
      "versionId": 22,
      "title": "Manual de Calidad ISO 9001",
      "versionNumber": "2.0",
      "contentUrl": null,
      "matchedIn": "metadata+content",
      "snippet": "…Política de calidad de la organización conforme a ISO 9001:2015…"
    },
    {
      "source": "postgres-index",
      "documentId": 7,
      "versionId": 14,
      "title": "Procedimiento de Auditoría ISO 9001",
      "versionNumber": "1.2",
      "contentUrl": "https://storage.example.com/docs/auditoria.pdf",
      "matchedIn": "title",
      "snippet": "Procedimiento de Auditoría ISO 9001"
    }
  ]
}

GET /search/suggest

Returns up to 10 document title suggestions matching a partial query string. Intended for powering autocomplete UI components. Requires at least 2 characters in q. Auth: Bearer token
Module access: MODULE_3 — OPERATOR, COMPANY_ADMIN, SUPER_ADMIN

Query parameters

string

required

Partial title string to match against. Must be at least 2 characters; shorter values return { "suggestions": [] } immediately without querying MongoDB.

curl -G https://api.qualitydocd.example/api/search/suggest \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "q=man"

Response

suggestions

array

Array of up to 10 suggestion objects matched by case-insensitive regex on the title field of the MongoDB document_metadata collection.

Show suggestion fields

integer

The documentId of the matching document.

title

string

The full document title.

{
  "suggestions": [
    { "id": 12, "title": "Manual de Calidad ISO 9001" },
    { "id": 15, "title": "Manual de Procedimientos Internos" }
  ]
}

If MongoDB is unavailable, this endpoint returns an empty suggestions array rather than an error, to avoid breaking autocomplete UI flows.

POST /search/index

Manually tokenizes and (re)indexes a document version into the PostgreSQL search_index table. Any existing index entry for the given version is deleted and replaced. Auth: Bearer token
Module access: MODULE_1 — OPERATOR, COMPANY_ADMIN, SUPER_ADMIN

Request body

versionId

integer

required

The ID of the document version to index. Must belong to the authenticated user’s company.

curl -X POST https://api.qualitydocd.example/api/search/index \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": 22 }'

How indexing works

The endpoint retrieves the version and its parent document, then calls the tokenizer on both:

titleTokens — tokens derived from the document’s title
bodyTokens — tokens derived from the version’s contentText
tokens — the deduplicated union of both arrays

The tokenizer lowercases and accent-normalizes the input, removes punctuation, splits on whitespace, discards tokens shorter than 3 characters, and filters out a built-in stop-word list (English and Spanish). The existing search_index row for the version is deleted before the new row is inserted, ensuring a clean re-index.

Response `200`

indexed

boolean

Always true on success.

tokenCount

integer

Total number of unique tokens stored in the tokens array for this version.

{
  "indexed": true,
  "tokenCount": 47
}

Indexing is triggered automatically when a version is approved via POST /documents/:id/versions/:versionId/approve. Use this endpoint only when you need to manually re-index a version — for example, after correcting data or recovering from a failed approval.

Error responses

Status	Body	Cause
`400`	`{ "error": "versionId requerido" }`	`versionId` was missing or not a valid integer
`404`	`{ "error": "Version not found" }`	No version with that ID exists in the user’s company

Authentication

Documents

Platform

Search API — Full-Text and Metadata Document Search

GET /search

Query parameters

How search works

Response

GET /search/suggest

Query parameters

Response

POST /search/index

Request body

How indexing works

Response `200`

Error responses

Build docs developers (and LLMs) love

Authentication

Documents

Platform

Documentation Index

​GET /search

​Query parameters

​How search works

​Response

​GET /search/suggest

​Query parameters

​Response

​POST /search/index

​Request body

​How indexing works

​Response 200

​Error responses

Build docs developers (and LLMs) love

GET /search

Query parameters

How search works

Response

GET /search/suggest

Query parameters

Response

POST /search/index

Request body

How indexing works

Response `200`

Error responses