ConnectCloud Developers

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:

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

View as Markdown · Interactive reference · OpenAPI