Full-text search across entities (tenant:search:read)
GET /api/search/v1/query
Module: Search · operationId: searchRecords · Tag: Search · Auth: access token (Authorization: Bearer <accessToken>)
Full-text search over the records of the requested entities (all nineteen when omitted)
that the caller may open. Needs q, at least one f_title/f_text filter, or both.
Query syntax (q) – web search syntax: words are combined with AND, "exact phrase"
matches the words in this order, a or b either word, -word excludes it. Words match by
their stem (Rechnungen finds Rechnung); accents and case are ignored. Other characters
(*, ?, +, |, ~, the former query string syntax) have no special meaning. q and
the filter values together are at most 500 characters (400 invalid, field: q).
fields (the former field list) is accepted and ignored.
Field filters (f_title, f_text) – their values are added to the search text, so a
hit matches them in its title or its text (until November 2026 f_title matched the title
only). Other f_<field> parameters are ignored.
Result – hits best first (Reciprocal Rank Fusion of the modules' lists, see Model), each
with the entity's former index name (<customerNo>-<tenantName>-<entity>, lower case), its
entity in _entity, the record in _source and the matched words of its text in
highlight.text. Every module is asked for from + size hits; hits.total.value counts the
hits collected that way (at most 500) and is a lower bound (relation: gte) when a module
answered all it was asked for; relation: eq means the result is probably complete (no
module had more to give, failed modules aside). aggregations.entities.buckets counts the
collected hits per index. When a module failed, degraded is true and failedModules names
it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q |
query | string | Search text in simple query string syntax (see the operation description). | |
entities |
query | array of Entity | Comma-separated entities to search; case-insensitive, surrounding spaces and duplicates are ignored. Omitted or empty means all nineteen. An unknown entity fails with 400 invalid (field: entities). |
|
fields |
query | array of string | Ignored (until November 2026 the fields q was matched against). Every module searches the title and text of its records. |
|
fieldFilters |
query | object | Field filters, one query parameter per field: the parameter name is f_ followed by the field name, f_title=Wartung or f_text=Heizung (there is no parameter called fieldFilters; its keys are the parameter names). Only the first value of a repeated parameter counts. The values are added to the search text (a hit matches them in its title or text). Other fields are ignored. |
|
from |
query | integer | 0-based offset of the first hit. A negative or non-numeric value is 400 invalid. (default 0) |
|
size |
query | integer | Page size, 1–100. Any other value is 400 invalid; from + size must not exceed 500 (field: from). (default 20; max 100) |
Responses
- 200 One page of hits (
application/json) - 400
invalid: missing search text (q/query, or forGET /queryalso no field filter), a search text over 500 characters (field: q), an unsupported entity (field: entities),from/sizeoutside their range (from + sizeover 500:field: from) or a body that is not valid JSON.fieldnames the parameter. (application/json) - 401 No bearer token, or an invalid or expired one (empty body).
- 403 The token lacks
tenant:search:reador is a service token (forbidden), or carries no active tenant (tenant_required). (application/json) - 500 No module asked could answer (
internal). Details are only logged. (application/json)
Fields of the 200 answer:
_shards(Shards): Deprecated: the former search engine's shard counts, kept within v1 with the meaning of the federation – one "shard" per module asked. UsedegradedandfailedModulesinstead.failed(integer): Modules that failed or missed their deadline (the length offailedModules).skipped(integer): Always 0.successful(integer): Modules that answered.total(integer): Modules asked.
aggregations(object): Counts of the collected hitsentities(object): Number of collected hits per index (not only those of the page).buckets(array of object): One bucket per index with hitsdoc_count(integer): Collected hits of the indexkey(string): Index name<customerNo>-<tenantName>-<entity>.
doc_count_error_upper_bound(integer): Always 0sum_other_doc_count(integer): Always 0
degraded(boolean): True when a module failed or did not answer in time; the hits are then those of the other modules.degradedReason(string): Present only when degraded is true. (one ofmodules_unavailable)failedModules(array of string): The modules whose entities are missing from the answer; present only when one failed.hits(object): The hits of the page with their totalhits(array of SearchHit): The hits of the page, best first_entity(string): Entity of the hit (<module>-<type>)._id(string): Record id within the entity._index(string): The entity's former index name,<customerNo>-<tenantName>-<entity>in lower case._score(number): Reciprocal Rank Fusion score (1 / (60 + place)in its module's list); only the order means something._source(SearchDocument): One record of a module entity (<module>-<type>). Until November 2026textheld the whole searchable text andaudiencewas filled.customerNo(string, required): Customer number of the tenant the record belongs to.id(string, required): Record id of the module (unique within the entity).module(string, required): Owning module:desk,crm,masterdata,trade,knowledge,hr,comms,dmsorforge.tenantName(string, required): Tenant name of the record.text(string, required): An excerpt of the record's text around the matches (plain text), or its start.title(string, required): Title of the record.type(string, required): Record type within the moduleupdatedAt(string (date-time), required): Time of the last change of the record.audience(array of string): Deprecated and no longer sent (since November 2026): who may see a record is decided by its module at search time, with the caller's own read rights. Until then the principals of the former index (tenant,perm:<permission>,user:<email>,group:<id>).ref(object): What opening the record needs besidesid, only for some types (ids and keys, not searchable): the record it belongs to or the parts of its address.desk-comment:itemId;knowledge-pageandknowledge-comment:space(space key) andpath(page path);trade-sales_documentandtrade-sales_item:transactionId,transactionTypeandtransactionNumberof the sales document;masterdata-contact:addressId;comms-message:deliveryId(its newest delivery);crm-csat:responseId.
highlight(object): The matched words of the record's text:textholds one excerpt with the matches wrapped in<em>…</em>; the rest is plain text, not HTML (render it as text). Missing when the excerpt has no match (e.g. a match in the title only).
max_score(number, nullable): Score of the best hit.total(object): Number of hits collectedrelation(string):gtewhenvalueis a lower bound (a module answered all it was asked for, more may exist);eq: probably complete. (one ofeq,gte)value(integer): Number of hits collected: every module is asked forfrom + sizehits; at most 500. (max 500)
timed_out(boolean): True when a module did not answer within its deadline (it is infailedModules).took(integer): Search time in milliseconds.
Example 200 answer:
{
"_shards": {
"failed": 0,
"skipped": 0,
"successful": 8,
"total": 8
},
"aggregations": {
"entities": {
"buckets": [
{
"doc_count": 1,
"key": "10001-hauptmandant-desk-item"
},
{
"doc_count": 1,
"key": "10001-hauptmandant-knowledge-page"
}
],
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0
}
},
"degraded": false,
"hits": {
"hits": [
{
"_entity": "desk-item",
"_id": "7f3c2a4e-0000-4000-8000-000000004711",
"_index": "10001-hauptmandant-desk-item",
"_score": 0.01639344262295082,
"_source": {
"customerNo": "10001",
"id": "7f3c2a4e-0000-4000-8000-000000004711",
"module": "desk",
"tenantName": "hauptmandant",
"text": "Der Drucker im Empfang meldet einen Papierstau, der Fehler kehrt zurück.",
"title": "Drucker im Empfang streikt",
"type": "item",
"updatedAt": "2026-09-14T08:12:00Z"
},
"highlight": {
"text": [
"Der Drucker im \u003cem\u003eEmpfang\u003c/em\u003e meldet einen Papierstau, der Fehler kehrt zurück."
]
}
},
{
"_entity": "knowledge-page",
"_id": "3b1e9d20-0000-4000-8000-000000000142",
"_index": "10001-hauptmandant-knowledge-page",
"_score": 0.01639344262295082,
"_source": {
"customerNo": "10001",
"id": "3b1e9d20-0000-4000-8000-000000000142",
"module": "knowledge",
"ref": {
"path": "drucker/wartung",
"space": "it"
},
"tenantName": "hauptmandant",
"text": "Wartungsschritte für den Etagendrucker im Empfang.",
"title": "Druckerwartung im Empfang",
"type": "page",
"updatedAt": "2026-08-02T10:00:00Z"
},
"highlight": {
"text": [
"Wartungsschritte für den Etagendrucker im \u003cem\u003eEmpfang\u003c/em\u003e."
]
}
}
],
"max_score": 0.01639344262295082,
"total": {
"relation": "eq",
"value": 2
}
},
"timed_out": false,
"took": 42
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/search/v1/query' \
-H "Authorization: Bearer $ACCESS_TOKEN"