Search knowledge files

knowledgeSearch(projectReference: ID!, input: KnowledgeSearchInput!): KnowledgeSearchResult!

Arguments

ArgumentTypeRequiredDescription
projectReferenceID!YesProject whose knowledge is selected. Ordinary callers require project.knowledge.read. A run-bound MCP service credential instead must match the persisted run's project and agent plus its actor or runtime transport binding; its effective sealed authority must grant the invoked tool and a knowledge selector. On project-scoped MCP endpoints, the scoped project supplies this value when omitted.
inputKnowledgeSearchInput!Yes

Input fields

input

KnowledgeSearchInput

FieldTypeRequiredDescription
queryStringNoText to match against knowledge file paths and frontmatter, 1 to 500 characters. Required on the first page.
cursorStringNoThe previous page's pageInfo.endCursor.
lookupTargetKnowledgeLookupTargetInputNoSource to search; omit for the main preview branch.
limitIntNoFiles per page, 1 to 12; default 6.
shardCountIntNoNumber of shards, 1 to 8; default 1.
shardIndexIntNoShard to read, 0 to shardCount - 1.

Response

Returns KnowledgeSearchResult!. Open the type for its fields and nested types.

FieldTypeDescription
queryString!Query used for scoring.
modeKnowledgeLookupMode!search when results scored positively; browse when no positive matches exist. Returns paths and metadata, falling back to a browse page when nothing matches.
data[KnowledgeLookupItem!]!Knowledge Markdown paths with frontmatter previews. Read selected files (MCP get_file) before answering knowledge questions.
pageInfoPageInfo!endCursor is the opaque cursor of the next page.
returnedInt!
totalMatchesInt!
shardKnowledgeLookupShard!
limitInt!Page size used for this page.

Types marked with ! cannot be null. Lists use [Type] notation. The type index lists all published input and response types.

Example

graphql
query KnowledgeSearch($projectReference: ID!, $input: KnowledgeSearchInput!) {
  knowledgeSearch(projectReference: $projectReference, input: $input) {
    limit
    mode
    query
    returned
    totalMatches
    data {
      matchedFields
      path
    }
    pageInfo {
      hasNextPage
      endCursor
      hasPreviousPage
      startCursor
    }
  }
}
json
{
  "projectReference": "00000000-0000-4000-8000-000000000001",
  "input": {}
}