Skip to main content
POST
Ask a question grounded in knowledge

Spend

Each answered ask runs a metered model request under the knowledge-api agent. Before it retrieves anything, ask reads the knowledge-api agent budget and the global budget. When either is frozen by an operator (the global spend freeze included) or exhausted, it answers 402 payment_required with a decisionId and calls no model; a person changes the budget in the Console. With no budget configured, ask answers. Spend is attributed to the calling External App when an app calls. A platform or Personal key’s ask is charged to the knowledge-api agent and the global budget, with no key or person attached.

From MCP

The Forge MCP server exposes this operation as forge_ask_knowledge, on the core list. Each call runs a metered model request, the same as over HTTP, and is refused the same way when the knowledge-api agent or global budget is frozen or exhausted. An MCP host that would rather reason over the chunks itself calls forge_search_knowledge, which returns up to limit chunks (default 10) of every kind; ask retrieves its own top 5, sends only chunks whose similarity is at least 0.2, and drops hits only the text search found. See MCP server — Knowledge. When the search behind the answer reaches its candidate cap before the ranking settles, the response carries meta.partial: true.

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
Minimum string length: 1
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

Response

Grounded answer with its source chunks

data
object
required
meta
object
required