Skip to main content
POST
List knowledge records
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/records/list answers every record of the requested kinds in the credential’s readable namespaces, or refuses. It never answers a partial list as complete. It needs knowledge:read. Machine credentials still refuse a cohort containing a source-restricted record (permission_denied/restricted_records); a successful machine list reports omitted: {restricted: 0}. Credential ownership does not confer person access. See Knowledge records for what a record carries and when a kind is complete. A complete list answers in pages of 500 records in (kind, externalId) order. count and digest describe the whole admitted list, and omitted.restricted counts inaccessible active restricted candidates of the requested source/kinds before filtering. The count is pinned across every door page; an omission-only change also refuses changed. nextCursor is set while records remain. Every page reads the complete list again and is pinned to it: when the records change between pages, the page refuses changed, and you start again without a cursor. A cursor sent with a different request refuses invalid_filter. Every refusal answers 200 with its status and reason:
The required omitted object changes the current strict output contract. Released snapshots remain immutable; the separately authorized containing MCP release must satisfy its existing next-major compatibility requirements. No new request field selects a person or supplies a reader.

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
kinds
string[]
required

Record kinds, <provider>.<name> (for example freshservice.group).

Required array length: 1 - 8 elements
Minimum string length: 1
sourceId
string

The source to read from. Required when two readable sources provide a kind (ambiguous_source).

Minimum string length: 1
collectionId
string

The authored collection to read from. Mutually exclusive with sourceId.

Minimum string length: 1
namespaces
string[]

Narrow to these namespaces, each in the caller's readable set.

Minimum string length: 1
filter
object

A typed filter over the kinds' stored schemas: {and}, {or}, {not}, {attr, op: eq|ne|in|exists, value?}, {ref, op: includes, externalId} or {parentExternalId}; at most 10 leaves and depth 3. An unknown name or type refuses invalid_filter.

cursor
string

The previous page's nextCursor, with the same request.

Minimum string length: 1
limit
integer
default:500

Records per page, 1 to 500 (default 500); a larger value is 400 too_big.

Required range: 1 <= x <= 500
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

Response

One page of the complete list, or a refusal

data
object
required

One page of a complete record list, or a refusal. complete: at most 500 records in (kind, externalId) order, count and digest of the complete admitted list, and omitted.restricted counting inaccessible active restricted candidates of the requested kinds before filtering (the same whole-cohort count on every door page), and nextCursor while records remain. Otherwise a refusal with its reason: incomplete, stale, too_large, not_listable, ambiguous_source, permission_denied, invalid_filter or changed.

meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.