# ConnectCloud Search API (v1.0.0)

Full-text search over the tenant's desk, CRM, master data, trade, knowledge, HR and comms records and its DMS documents.

Base URLs:

- Production: `https://api.mbcom.cloud/api/search/v1`
- Staging: `https://api.mbcom.cloud/api/search/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/search`

Search finds records of a tenant across the ConnectCloud modules (desk, CRM, master data,
trade, knowledge, HR, comms) and its DMS documents with one query. It only reads: each module
searches its own records and answers the best matches the caller may open; this API asks the
modules in parallel and merges their answers into one ranked list.

## Model
- Searchable records are grouped into **entities**, `<module>-<type>`; every entity is served
  by its module:

  | Entity | Module, type | Contents |
  |---|---|---|
  | `desk-item` | desk, item | Tickets, issues and tasks |
  | `desk-comment` | desk, comment | Comments on desk items |
  | `crm-lead` | crm, lead | Leads |
  | `crm-campaign` | crm, campaign | Campaigns |
  | `crm-opportunity` | crm, opportunity | Opportunities |
  | `crm-csat` | crm, csat | Customer satisfaction records |
  | `masterdata-address` | masterdata, address | Addresses (customers, suppliers) |
  | `masterdata-contact` | masterdata, contact | Contacts |
  | `masterdata-product` | masterdata, product | Products |
  | `trade-sales_document` | trade, sales_document | Sales documents |
  | `trade-sales_item` | trade, sales_item | Items of sales documents |
  | `trade-contract` | trade, contract | Contracts |
  | `knowledge-page` | knowledge, page | Knowledge pages |
  | `knowledge-comment` | knowledge, comment | Comments on knowledge pages |
  | `hr-recruiting_posting` | hr, recruiting_posting | Job postings |
  | `hr-org_unit` | hr, org_unit | Organisational units |
  | `comms-message` | comms, message | Messages |
  | `dms-document` | dms, document | DMS documents: the title (or the file name) and the extracted text (encrypted documents and documents in restricted folders are never indexed) |
  | `forge-item` | forge, item | Development items (`APP-12`): reference, title, description and sections (confidential items only for whom they are meant, converted items left out) |
  | `forge-comment` | forge, comment | Comments on development items |
  | `forge-project` | forge, project | Development projects: key, name and description |

  A hit carries the record's `id`, `title`, `module`, `type`, `updatedAt`, for some types
  `ref`, and in `text` an excerpt of the record's text around the matches.
- **Tenant isolation:** the tenant is always taken from the token (`customerNo` and
  `tenantName` claims); there is no parameter to address another tenant. Entity names are
  checked against a fixed list (`400 invalid`, `field: entities`).
- **Full-text search** (`GET /query`) is the supported search for integrations. Each module
  searches with German full text (words are reduced to their stem, accents are ignored);
  titles weigh more than the text. A search text of at most four characters also matches
  titles that contain it as part of a word (`Mül` finds `Müller`).
- **Ranking across modules:** the modules' ranked lists are merged by Reciprocal Rank Fusion:
  a hit at place `r` of its module's list scores `1 / (60 + r)`. The best hits of every
  module therefore come first, the modules in the order of the entity table on ties. The
  score says nothing beyond the order.
- **Partial answers:** a module that fails or does not answer within its deadline (a few
  seconds) is left out; the answer then holds the other modules' hits, `degraded: true` and the
  module in `failedModules`. Only when no module asked could answer is the search `500 internal`.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:search:read` | every search route of this API |

`tenant:search:read` is grantable to tenant roles ("Suche") and can be given to API keys
and the AI assistant. It was called `tenant:opensearch:read` until November 2026; roles and API keys
got the new name automatically, and the old name is no longer accepted.
The permission only opens the routes. **What a search returns is what the caller may open:**
the caller's token is handed to every module, and each module answers only records its own
read rules let that caller read (e.g. desk tickets of spaces the caller is a member of, sales
documents only with `tenant:trade:sales:read`). A record of another tenant is never returned.
Service tokens are refused (`403 forbidden`): a search always runs as a person, an API key or
the assistant.

## Conventions
- Pagination is offset based: `from` (0-based offset, at least 0) and `size` (page size, 1–100,
  default 20); `from + size` must not exceed 500 (until November 2026: 10,000). Values outside
  these ranges are refused with `400 invalid` naming the parameter in `field` – they are never
  adjusted. Every module ranks at most 500 hits per search, so deeper pages do not exist.
- Errors follow the shared shape `{error, code, field?, details?}` (see the errors guide):
  `invalid` (400, with `field`), `forbidden` (403), `tenant_required` (403), `internal` (500, no
  module could answer; details are only logged). `401` responses from the authentication
  layer have an empty body.
- Responses keep the shape of the former search engine result (`hits.total`, `hits.hits[]` with
  `_index`, `_id`, `_score`, `_source`, `highlight`), plus `degraded` and `failedModules`.

# Search

## 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"
```

## Full-text search across entities, POST variant (tenant:search:read)

`POST /api/search/v1/query`

Module: Search · operationId: `searchRecordsByPost` · Tag: Search · Auth: access token (`Authorization: Bearer <accessToken>`)

Same search as `GET /query` with the same query-string parameters. A request body is not
read: `q`, `entities`, `fields`, `f_<field>`, `from` and `size` must be sent in the query
string. Prefer `GET /query`.

### 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 POST 'https://api.mbcom.cloud/api/search/v1/query' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

