## 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 for `GET /query` also no field filter), a
search text over 500 characters (`field: q`), an unsupported entity (`field: entities`),
`from`/`size` outside their range (`from + size` over 500: `field: from`) or a body that is
not valid JSON. `field` names the parameter.
 (`application/json`)
- **401** No bearer token, or an invalid or expired one (empty body).
- **403** The token lacks `tenant:search:read` or 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. Use `degraded` and `failedModules` instead.
  - `failed` (integer): Modules that failed or missed their deadline (the length of `failedModules`).
  - `skipped` (integer): Always 0.
  - `successful` (integer): Modules that answered.
  - `total` (integer): Modules asked.
- `aggregations` (object): Counts of the collected hits
  - `entities` (object): Number of collected hits per index (not only those of the page).
    - `buckets` (array of object): One bucket per index with hits
      - `doc_count` (integer): Collected hits of the index
      - `key` (string): Index name `<customerNo>-<tenantName>-<entity>`.
    - `doc_count_error_upper_bound` (integer): Always 0
    - `sum_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 of `modules_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 total
  - `hits` (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 2026 `text` held the whole searchable text and `audience` was 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`, `dms` or `forge`.
      - `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 module
      - `updatedAt` (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 besides `id`, only for some types (ids and keys, not searchable): the record it belongs to or the parts of its address. `desk-comment`: `itemId`; `knowledge-page` and `knowledge-comment`: `space` (space key) and `path` (page path); `trade-sales_document` and `trade-sales_item`: `transactionId`, `transactionType` and `transactionNumber` of 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: `text` holds 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 collected
    - `relation` (string): `gte` when `value` is a lower bound (a module answered all it was asked for, more may exist); `eq`: probably complete. (one of `eq`, `gte`)
    - `value` (integer): Number of hits collected: every module is asked for `from + size` hits; at most 500. (max 500)
- `timed_out` (boolean): True when a module did not answer within its deadline (it is in `failedModules`).
- `took` (integer): Search time in milliseconds.

Example 200 answer:

```json
{
  "_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

```bash
curl -X GET 'https://api.mbcom.cloud/api/search/v1/query' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
