Search knowledge chunks
Vector and text search, fused by rank, over the namespaces the caller can read. Requires permission knowledge:read.
Narrowing by form
form narrows the search to case (knowledge entries) or record (synchronized records of searchable kinds). Without it, both are searched. Search is ranked and partial; to read every record of a kind, use records/list. Any other value answers 400.
kinds selects one to eight exact registered record-kind keys, such as freshservice.group. It implies form: "record"; combining it with form: "case" is refused. Duplicate keys are normalized. An empty selection, malformed key, or unknown key answers 400. A known kind with no matching searchable records returns an empty chunks array. Kind selection does not broaden the caller’s readable scopes or source access.
Response chunks
Each chunk carries exactly theKnowledgeChunk fields: id, content, score, similarity (absent for a hit only the text search found), contentType, sourceType, source (ref, and fetchUrl, always null), scopeType, scopeId, tags, createdAt, and, when they apply, a case’s grade and a pending revision’s revisionOf. A case’s internal grading version and verification bookkeeping (caseVersion, verifiedAt, verifiedBy, verificationDueAt) are never returned; before 2026-09-30 the last three could appear on a recorded case although no schema documented them.
The HTTP response contains the retrieved content. The MCP tool forge_search_knowledge projects bounded discovery excerpts, preserving chunk identity, ranking and provenance, and reports truncation in meta; use a full entry read to verify an SOP. See MCP server — Knowledge.
A person’s own key or a platform key can search a Customer it may act for with scopeType: "customer" and scopeId: "<canonicalCustomerId>". That searches the Customer’s partition and its organization’s. Omitted scopes keep ambient discovery; see Selecting a Customer’s partition.
When the search’s candidate window reaches its cap before the ranking settles, the response carries meta.partial: true: the chunks are the best found so far, not a settled ranking.Authorizations
Body
The orgUnitId of the one external organization this request acts for (listed by GET /api/v2/knowledge/scopes/list with scopeType organization). It needs knowledge:read (knowledge:manage for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused actingFor answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500.
1 - 200Select 1–8 exact registered record-kind keys. Duplicates are normalized and record form is implied. Empty or unknown selections and an explicit case form are refused with 400. A known kind with no matching searchable records returns an empty chunks array.
1 - 8 elements1 - 128^[a-z0-9_]+\.[a-z0-9_]+$
