Skip to main content
GET
Get one knowledge scope's shape
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/scopes/get?namespace=<namespace> reads one namespace from scopes/list with its shape, so a client can see what a namespace holds before it lists anything. It needs knowledge:read. MCP hosts call it through forge_call_operation with operationId getKnowledgeScope. The body is the scope as scopes/list names it, { namespace, scopeType, entityId, label, readable, writable }, plus:
  • contentTypes: { contentType, count } for each content type with at least one active entry you may read, in the order document, message, workflow_output, note, session_summary, file, moment, snippet, case, record. A count is exactly what cases/list returns for that namespace and contentType: a source-restricted entry, an artifact waiting for a steward’s review and a pending revision are never counted, so no number describes knowledge you cannot read.
  • recordKinds: { kind, sourceId, collectionId } for each record kind you can list there, from a synchronized source you can read (sourceId) or an authored collection you are admitted to (collectionId); the other id is null. Pass the kind and that id to POST /api/v2/knowledge/records/list.
The read is bounded. When it stops before the end of the namespace, meta.partial is true and each count is a floor. A namespace you cannot read and one that does not exist answer the same 404 resource_missing. namespace is required and appears once; a missing, empty or repeated namespace, or any other query parameter, answers 400 bad_request.

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.

Path Parameters

scopeId
string
required

One knowledge namespace from scopes/list (for example company or team:<orgUnitId>).

Minimum string length: 1

Response

The scope and its shape

data
object
required

One readable knowledge scope as scopes/list names it, with how many active entries of each content type the caller may read in it (a type with none is left out) and the record kinds it can list there, each with the sourceId or collectionId that provides it (pass it to records/list). A count is exactly what cases/list returns for that namespace and type: a source-restricted entry, an artifact held for review and a pending revision are never counted. meta.partial says the read budget stopped the read, so each count is a floor.

meta
object
required