Skip to main content
POST
Search knowledge chunks

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 the KnowledgeChunk 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

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Body

application/json
prompt
string
required

The search query.

Minimum string length: 1
topK
integer
default:10
Required range: 1 <= x <= 50
scopeType
string

Knowledge scope type to target. The resulting namespace must be in the caller's readable (reads) or writable (writes) set, or the request answers 403.

scopeId
string

Entity id for a scope that carries one. Requires scopeType.

actingFor
string

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.

Required string length: 1 - 200
form
enum<string>

Narrow the search to cases or to records of searchable kinds; absent, both are searched.

Available options:
case,
record
kinds
string[]

Select 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.

Required array length: 1 - 8 elements
Required string length: 1 - 128
Pattern: ^[a-z0-9_]+\.[a-z0-9_]+$

Response

Matching chunks

data
object
required
meta
object
required