Skip to main content
GET
List knowledge cases
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

GET /api/v2/knowledge/cases/list lists the cases in the credential’s readable namespaces, or in the one readable namespace it names, newest first by default. It needs knowledge:read. A source-restricted case is never returned, even to your own MCP key. See Knowledge cases for what a case carries and what it never carries. Each page reads up to limit candidate rows and returns those that match and are readable, so a page may hold fewer cases than limit, or none, while meta.hasMore is true. Follow meta.nextCursor until it is null. Any other parameter, a value outside its set, an empty or repeated single-valued parameter, or a cursor Forge cannot read answers 400 bad_request. A title sort answers 400 while case titles are still being prepared after an upgrade. An empty search page is not proof that a key is unused. Use Get case by exact namespace and key for deterministic SOP duplicate checks. A Personal MCP key can explicitly select one authorized customer:<canonicalCustomerId> namespace; omitting it never enumerates Customer partitions.

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.

Query Parameters

namespace
string

One readable knowledge namespace (company, team:<orgUnitId>, …). An unreadable namespace answers 403.

Minimum string length: 1

A case-insensitive substring of the case's title, summary, key or source id (1–500 characters).

Required string length: 1 - 500
scopeType
enum<string>[]

Only cases in these scope types. Repeat the parameter for several values; any other value answers 400.

Available options:
personal,
team,
department,
company,
global,
factory,
project,
direct,
group,
system,
agent,
external_app,
customer,
organization
contentType
enum<string>[]

Only entries of these content types. Repeat the parameter for several values; any other value answers 400.

Available options:
document,
message,
workflow_output,
note,
session_summary,
file,
moment,
snippet,
case,
record
sourceType
enum<string>[]

Only entries from these sources. Repeat the parameter for several values; any other value answers 400.

Available options:
upload,
chat_save,
auto_ingest,
session_close,
memory_promotion_agent,
memory_promotion_human,
memory_promotion_threshold,
memory_promotion_compression,
agent_record,
external_sync
grade
enum<string>[]

Only cases with these grades; ungraded matches an entry with none. Repeat the parameter for several values; any other value answers 400.

Available options:
provisional,
proven,
contested,
retired,
ungraded
artifactKind
enum<string>[]

Only cases of these artifact kinds; unclassified matches a case with none. Repeat the parameter for several values; any other value answers 400.

Available options:
lesson,
policy,
how_to,
reference,
faq,
note,
unclassified
collectionId
string

Only the artifacts filed in this subject collection (from subjectCollections/list); records and artifacts waiting for review are never listed. A collection that is unknown, archived or out of the caller's reach answers the same 404.

Minimum string length: 1
sort
enum<string>
default:newest

newest (default), oldest or title. A title sort answers 400 while titles are still being prepared after an upgrade.

Available options:
newest,
oldest,
title
cursor
string

The meta.nextCursor from the previous page; omit for the first page.

limit
integer
default:25

Candidate rows read for this page, 20–80 (default 25).

Required range: 20 <= x <= 80
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

Readable knowledge cases

data
object[]
required
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.