> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge

> Search, ask, add, read and export knowledge; curate cases and review items; manage golden sets and external sources; and read knowledge health and the Learning feed.

> [!NOTE]
>
> This family overview describes the **v2 compatibility API**. Its linked operation pages render current v3 request schemas. Keep each version's method, path, and payload together.

The Knowledge API exposes Forge's knowledge store to external applications: chunk retrieval by vector and text search fused by rank, answers grounded in retrieved chunks, ingestion, reading one entry, deleting one entry, exporting a namespace, and reading the health of the knowledge a credential can read.

Every endpoint requires a `Bearer` credential (an External App credential or a platform API key) with the scope listed below. All responses use the `{ data, meta: { requestId } }` envelope; errors use `{ error: { code, message }, meta }`.

## Scopes

| Scope | Grants |
| - | - |
| `knowledge:read` | `getChunks`, `ask`, `getKnowledge`, `getKnowledgeHistory`, `getKnowledgeHealth`, `listSynchronizedSources`, `getSynchronizedSource`, `listSynchronizedSourceRuns`, `listKnowledgeCases`, `getKnowledgeCase`, `listKnowledgeCaseVersions`, `getKnowledgeCaseRevision`, `listKnowledgeCaseUses`, `listKnowledgeGoldenSets`, `listKnowledgeGoldenSetRuns`, `listKnowledgeScopes`, `getKnowledgeSettings`, `getLatestKnowledgeReembedRun`; `listReviews`, `getReview`, `listLearning` (held at the deployment root) |
| `knowledge:write` | `addKnowledge` |
| `knowledge:manage` | `deleteKnowledge`, `exportKnowledge`, `retryKnowledgeEntry`, `requestSynchronizedSourceSync`, `updateSynchronizedSource`, `removeSynchronizedSource`, `relistSynchronizedSource`, `createKnowledgeCase`, `updateKnowledgeCase`, `verifyKnowledgeCase`, `setKnowledgeCaseGrade`, `setKnowledgeCaseSteward`, `decideKnowledgeReview`, `createKnowledgeGoldenSet`, `updateKnowledgeGoldenSet`, `runKnowledgeGoldenSet`, `startKnowledgeReembed` |
| `knowledge:manage` and `credentials:use` | `createSynchronizedSource`, `listSynchronizedSourceProviders`: each requires both |
| `platform:manage` | `setKnowledgeSetting` (an elevated scope) |

`knowledge:manage` maps to the `knowledge:manage` permission. `knowledge:write` does not grant deletion. Connecting a source needs both `knowledge:manage` and `credentials:use`: a source syncs with the credential on its vendor's connection that resolves along its target scope, so connecting one uses that credential. `platform:manage` is an approve-and-administer scope: a Personal key carrying it expires sooner, and a Forge agent is refused it.

## Scope resolution

`getChunks`, `ask` and `addKnowledge` accept optional `scopeType` and `scopeId` fields to target one knowledge namespace. The platform resolves which namespaces the caller may read and write from the credential, never from the request. A request that names a namespace outside that set gets HTTP 403 with error code `forbidden`.

| Caller | Readable namespaces | Writable namespaces |
| - | - | - |
| External App | Its own `external_app:<appId>` namespace. The namespaces of its owner: `factory`, `project`, `team` for its owning org unit, and `department` for each parent org unit. `company` and `global`. | Its own `external_app:<appId>` namespace and the `factory`, `project` and `team` namespaces of its owner. `company` only if it holds `knowledge:manage`. |
| Platform API key without an app | `company`, `global` | `company`, only if the key holds `knowledge:manage` |
| Your own Personal key | Everything you can read in Forge: your `personal` namespace, your team and department, the factories and projects you belong to, `company` and `global`. | Your `personal` namespace, your own team, and the factories and projects you belong to. `company` only if the key holds `knowledge:manage`. |

`global` is never writable through the API. Company knowledge needs human approval, so every caller (an External App, a platform API key or your own Personal key) writes to `company` only while it holds `knowledge:manage` at the company scope. Without it, a `company` write answers 403 with error code `forbidden`. An organization's partition is reachable only by acting for it (below); `personal` is reachable only through your own Personal key, for your own namespace. Through the API, a source-restricted entry is never returned, even to your own Personal key. Your own Personal key also reads an entry only when the entry belongs to an org unit where you hold `knowledge:read`, as the Console does: search, `get`, history, the case reads and case writes, pending retries, the review queue, the learning feed, health, export and citation lookups all leave out an entry that belongs elsewhere, and a direct read of one is refused the way a read of an entry in a namespace you cannot read is. An External App and a platform API key are limited by namespace only.

When `scopeType` is omitted, `getChunks` and `ask` search `global` and `company`, plus the calling app's own `external_app` namespace. For your own Personal key, they search every namespace you can read. `addKnowledge` writes to `company`, so it needs `knowledge:manage` too.

Each entry records who added it, with the credential's attribution: the person who owns a Personal key (the key is named on the audit event), the External App as `external-app:<id>`, or a platform API key as `platform-key:<id>`.

An entry's governing organization and its knowledge namespace answer different questions. The governing `orgUnitId` determines who may manage and read the entry; the namespace says where the knowledge applies. For example, Gloo-owned support instructions about a Customer remain governed by Gloo's root Organization while using that Customer's namespace for agent retrieval. A grant on the Customer Organization alone does not grant access to Gloo-owned entries. The explicit Personal-key Customer paths use this same ownership/applicability distinction.

`scopeType` must be a knowledge scope type: `personal`, `team`, `department`, `company`, `global`, `factory`, `project`, `external_app`, `customer`, `agent`, `direct`, `group` or `system`. An unknown one answers 400. A known one whose namespace is outside the caller's set answers 403; `agent`, `direct`, `group` and `system` remain unreachable through these API paths. An organization is selected with `actingFor`, never with `scopeType`: `scopeType: "organization"` answers 400.

### Acting for an organization

Gloo's own knowledge lives in `company`. Each external organization's knowledge lives in its own partition, `organization:<orgUnitId>`, homed at that organization's unit. A request reads Gloo's knowledge unless it names one organization with `actingFor`, the organization's `orgUnitId`; it never reads two organizations at once, and an organization is never chosen from a stored row or by an agent on its own.

These operations take `actingFor`: `getChunks`, `ask` and `get` (body), `cases/list` and `cases/get` (query), `cases/update` (body), and `records/list` and `records/get` (body). Acting for an organization needs `knowledge:read` (`knowledge:manage` for `cases/update`) at that organization's own unit or at platform scope, held by the caller's worker and narrowed by the credential's scopes. A grant on Gloo's root does not reach an organization, and a person on an organization's side cannot act for another one. The organization must be active.

* `GET /api/v3/knowledge-scopes` lists each organization the caller may act for, with `scopeType` `organization` and its `orgUnitId` as `entityId`. Pass that id as `actingFor`.
* A refused `actingFor` answers 403 `forbidden`; it never falls back to Gloo's knowledge alone. A malformed one answers 400.
* An admitted read is recorded (`knowledge_acting_for_read`) before it is answered. A read whose record cannot be written answers 500 and returns nothing.
* `cases/list` takes `actingFor` or `collectionId`, not both. Subject collections and record collections are selected by namespace, as before.
* A read by id without `actingFor` reads only Gloo's knowledge: an organization's case or entry answers 404, as any entry outside reach does.

In the Console, the knowledge page's **Acting for** picker offers the same organizations. Selecting one is recorded first; only then does the page read that organization's knowledge.

### Selecting a Customer's partition

While an organization's knowledge moves into its own partition, some of it is still in its linked Customer's `customer:<canonicalCustomerId>` partition. A case create, list or exact-key get that names that namespace, or a `getChunks` or `ask` with `scopeType: "customer"` and `scopeId: "<canonicalCustomerId>"`, selects the Customer's organization exactly as `actingFor` with its `orgUnitId` does. Reads need `knowledge:read` and writes `knowledge:manage`, held at that organization's own unit or at platform scope and narrowed by the credential's scopes; acting for it reads both its partition and the Customer's.

A person's own key and a platform API key may make the selection; an External App acts for no organization but its own. A Customer with no active organization, or one the caller may not act for, is refused, and the request never falls back to `company`. Take the canonical Customer ID from the [Customer directory](https://docs.gloo.com/forge/reference/http-api/customers); a name, abbreviation or department ID is not a Customer ID.

### Where a write or read is decided

A credential's route check is made at the deployment root. Some operations then decide again where the knowledge lives, exactly as the Console does:

* **Deployment-wide changes need a platform grant.** `startKnowledgeReembed`, `setKnowledgeCaseGrade`, the golden-set create, update and run operations, `updateSynchronizedSource`, `requestSynchronizedSourceSync`, `removeSynchronizedSource`, `relistSynchronizedSource`, `retryKnowledgeEntry` (`knowledge:manage`) and `setKnowledgeSetting` (`platform:manage`) answer `403 forbidden` to a credential that holds the key only on an org unit, the root included. The refusal says the key must be granted for the platform.
* **A case is verified or given a steward where it lives.** `verifyKnowledgeCase` and `setKnowledgeCaseSteward` need `knowledge:manage` at the case's org unit (else the deployment root), as `delete` does; an External App's own namespace is its own.
* **A source is connected where it writes.** `createSynchronizedSource` needs `knowledge:manage` and `credentials:use` at the target's home: the company root for a `company` source, else the target's team, department, factory or project.
* **Your own Personal key reads a synchronized source where you can.** Its source list, get and runs, the health report's source sections and the record list leave out a source homed outside your own `knowledge:read`. An External App keeps its namespace fence.
* **A source's held changes are reviewed and decided by a person where the source lives.** The [source review operations](#reviewing-a-source’s-held-changes) admit only a Personal key, and decide its owner as a person at the source's home after the route's root check.
* **An External App reads a synchronized record by id where its record list would.** `getKnowledgeRecord` and `getKnowledgeHistory` need the app's `knowledge:read` at the record's source home, as `listKnowledgeRecords` does.

## Operations

Reads:

* `POST /api/v3/knowledge-chunks/search` — [getChunks](https://docs.gloo.com/forge/reference/http-api/knowledge/get-chunks.md) — vector and text search over every namespace the request reads, fused by rank; returns the top-N chunks (`topK`, 1–50, default 10; `form` narrows to `case` or `record`), each with a rank `score` in (0, 1] and, when the vector search found it, its cosine `similarity`; no LLM synthesis. A recorded case's chunk also carries its `grade` (`provisional`, `proven` or `contested`); a `retired` case is never returned
* `POST /api/v3/knowledge/ask` — [ask](https://docs.gloo.com/forge/reference/http-api/knowledge/ask.md) — retrieves the 5 most relevant chunks and answers from those whose cosine `similarity` is at least 0.2; returns the answer, the source chunks and the model used. When no chunk reaches that floor, it answers that no relevant knowledge was found, with no chunks and `model` `"none"`, and calls no model. The floor is an interim value that has not yet been measured against production data
* `POST /api/v3/knowledge-entries/{entryId}/lookup` — [getKnowledge](https://docs.gloo.com/forge/reference/http-api/knowledge/get.md) — reads one entry and its text
* `GET /api/v3/knowledge-health` — [getKnowledgeHealth](https://docs.gloo.com/forge/reference/http-api/knowledge/health.md) — what is broken in the knowledge the caller can read, and how far behind it is (see [Knowledge health](#knowledge-health))
* `GET /api/v3/knowledge-reviews` — [listReviews](https://docs.gloo.com/forge/reference/http-api/knowledge/list-reviews.md) — pages the review queue; see [Review queue and Learning feed](#review-queue-and-learning-feed)
* `GET /api/v3/knowledge-reviews/{reviewId}` — [getReview](https://docs.gloo.com/forge/reference/http-api/knowledge/get-review.md) — reads one review item
* `GET /api/v3/knowledge-learning-events` — [listLearning](https://docs.gloo.com/forge/reference/http-api/knowledge/list-learning.md) — pages what the knowledge base learned in a window of at most 90 days
* `GET /api/v3/knowledge-synchronized-sources` — [listSynchronizedSources](https://docs.gloo.com/forge/reference/http-api/knowledge/list-sources.md) — lists the newest 100 sources in readable namespaces
* `GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}` — [getSynchronizedSource](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source.md) — reads one source without its configuration or access mappings
* `GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs` — [listSynchronizedSourceRuns](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-runs.md) — pages one readable source's runs, newest first, with redacted errors
* `GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/diff` — [getSynchronizedSourceDiff](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-diff.md) — reads one source's diff policy and its runs' review phases (a Personal key; see [Reviewing a source's held changes](#reviewing-a-source’s-held-changes))
* `POST /api/v3/knowledge-records/search` — [listKnowledgeRecords](https://docs.gloo.com/forge/reference/http-api/knowledge/list-records.md) — every record of the requested kinds, complete or refused, in pages of 500 (see [Knowledge records](#knowledge-records))
* `POST /api/v3/knowledge-records/lookup` — [getKnowledgeRecord](https://docs.gloo.com/forge/reference/http-api/knowledge/get-record.md) — reads one record and its status
* `POST /api/v3/knowledge-snapshots/search` — [getKnowledgeHistory](https://docs.gloo.com/forge/reference/http-api/knowledge/history.md) — current-authorized prior versions for a case or record
* `GET /api/v3/knowledge-collections` — [listKnowledgeRecordCollections](https://docs.gloo.com/forge/reference/http-api/knowledge/list-collections.md) — lists Forge-owned record collections
* `GET /api/v3/knowledge-collections/{collectionId}` — [getKnowledgeRecordCollection](https://docs.gloo.com/forge/reference/http-api/knowledge/get-collection.md) — reads one record collection
* `POST /api/v3/knowledge-collections` — [createKnowledgeRecordCollection](https://docs.gloo.com/forge/reference/http-api/knowledge/create-record-collection.md) — creates a record collection in a writable namespace (`knowledge:manage` where it lives)
* `GET /api/v3/knowledge-subject-collections` — [listKnowledgeSubjectCollections](https://docs.gloo.com/forge/reference/http-api/knowledge/list-subject-collections.md) — lists the subject collections you read, with readable artifact counts; list one collection's artifacts with `GET /api/v3/knowledge-cases?collectionId=`
* `POST /api/v3/knowledge-collections/{collectionId}/records` — [createKnowledgeRecord](https://docs.gloo.com/forge/reference/http-api/knowledge/create-record.md) — adds an authored record
* `PATCH /api/v3/knowledge-collections/{collectionId}/records/{externalId}` — [updateKnowledgeRecord](https://docs.gloo.com/forge/reference/http-api/knowledge/update-record.md) — updates an authored record
* `DELETE /api/v3/knowledge-collections/{collectionId}/records/{externalId}` — [removeKnowledgeRecord](https://docs.gloo.com/forge/reference/http-api/knowledge/remove-record.md) — removes an authored record
* `GET /api/v3/knowledge-cases` — [listKnowledgeCases](https://docs.gloo.com/forge/reference/http-api/knowledge/list-cases.md) — pages the readable cases, filtered and sorted as the Console knowledge list (see [Knowledge cases](#knowledge-cases))
* `GET /api/v3/knowledge-case-lookup` — [getKnowledgeCase](https://docs.gloo.com/forge/reference/http-api/knowledge/get-case.md) — reads one case, its text, version and stewardship
* `GET /api/v3/knowledge-cases/{caseId}/versions` — [listKnowledgeCaseVersions](https://docs.gloo.com/forge/reference/http-api/knowledge/list-case-versions.md) — pages a case's past versions, newest first
* `GET /api/v3/knowledge-cases/{caseId}/revision` — [getKnowledgeCaseRevision](https://docs.gloo.com/forge/reference/http-api/knowledge/get-case-revision.md) — reads the edit held for review on a proven case
* `GET /api/v3/knowledge-cases/{caseId}/uses` — [listKnowledgeCaseUses](https://docs.gloo.com/forge/reference/http-api/knowledge/list-case-uses.md) — lists the runs and chat turns that cited a case
* `GET /api/v3/knowledge-golden-sets` — [listKnowledgeGoldenSets](https://docs.gloo.com/forge/reference/http-api/knowledge/list-golden-sets.md) — lists the retrieval golden sets whose every namespace the credential can read, each with its newest run and baselines (see [Retrieval golden sets](#retrieval-golden-sets))
* `GET /api/v3/knowledge-golden-sets/{goldenSetId}/runs` — [listKnowledgeGoldenSetRuns](https://docs.gloo.com/forge/reference/http-api/knowledge/list-golden-set-runs.md) — lists one golden set's eval runs, newest first
* `GET /api/v3/knowledge-synchronized-source-providers` — [listSynchronizedSourceProviders](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-providers.md) — lists the providers a source can be connected through (`knowledge:manage` and `credentials:use`)
* `POST /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers` — [listSynchronizedSourceContainers](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-containers.md) — lists the containers a new source at a writable target could read (`knowledge:manage` and `credentials:use`)
* `GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/kind-states` — [getSynchronizedSourceKindStates](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-kind-states.md) — reads a readable source's kinds: completeness, failing conditions and record counts
* `GET /api/v3/knowledge-settings` — [getKnowledgeSettings](https://docs.gloo.com/forge/reference/http-api/knowledge/get-settings.md) — reads the deployment's learning settings in force (see [Settings and re-embed](#settings-and-re-embed))
* `GET /api/v3/knowledge-reembed-latest-run` — [getLatestKnowledgeReembedRun](https://docs.gloo.com/forge/reference/http-api/knowledge/get-reembed-run.md) — reads the newest re-embed run's progress
* `GET /api/v3/knowledge-scopes` — [listKnowledgeScopes](https://docs.gloo.com/forge/reference/http-api/knowledge/list-scopes.md) — lists every knowledge scope the credential can read or write, with whether it may write each
* `GET /api/v3/knowledge-scopes/{scopeId}` — [getKnowledgeScope](https://docs.gloo.com/forge/reference/http-api/knowledge/get-scope.md) — reads one readable scope with its counts by content type and the record kinds it can list

Writes:

* `POST /api/v3/knowledge-entries` — [addKnowledge](https://docs.gloo.com/forge/reference/http-api/knowledge/add-knowledge.md) — ingests `document`, `note` or `snippet` content into one writable namespace; answers HTTP 201, or 200 when the `externalRef` was already added (see [Adding an entry](#adding-an-entry))
* `DELETE /api/v3/knowledge-entries/{entryId}` — [deleteKnowledge](https://docs.gloo.com/forge/reference/http-api/knowledge/delete.md) — deletes one entry in a writable namespace
* `GET /api/v3/knowledge-export` — [exportKnowledge](https://docs.gloo.com/forge/reference/http-api/knowledge/export.md) — returns a 24-hour download URL for NDJSON from one readable namespace: its active entries, and with `includeDeleted=true` its tombstones as metadata only
* `POST /api/v3/knowledge-entries/{entryId}/retry` — [retryKnowledgeEntry](https://docs.gloo.com/forge/reference/http-api/knowledge/retry-pending-entry.md) — embeds one stuck pending entry in a writable namespace again now (see [Remedies](#remedies))
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync` — [requestSynchronizedSourceSync](https://docs.gloo.com/forge/reference/http-api/knowledge/request-source-sync.md) — asks one source in a writable namespace to sync now
* `PATCH /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}` — [updateSynchronizedSource](https://docs.gloo.com/forge/reference/http-api/knowledge/update-source.md) — renames, retimes, pauses or resumes one source in a writable namespace
* `POST /api/v3/knowledge-synchronized-sources` — [createSynchronizedSource](https://docs.gloo.com/forge/reference/http-api/knowledge/create-source.md) — connects a source to a writable scope (HTTP 201; `knowledge:manage` and `credentials:use`, see [Knowledge sources](#knowledge-sources))
* `DELETE /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}` — [removeSynchronizedSource](https://docs.gloo.com/forge/reference/http-api/knowledge/remove-source.md) — removes one source in a writable namespace and permanently deletes every case it wrote
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist` — [relistSynchronizedSource](https://docs.gloo.com/forge/reference/http-api/knowledge/relist-source.md) — re-lists one source in a writable namespace from the start
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/review-diff` — [reviewSynchronizedSourceDiff](https://docs.gloo.com/forge/reference/http-api/knowledge/review-source-diff.md) — reads one page of a run's held changes as its reviewer may see them, recording the review (`knowledge:read`)
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/set-diff-policy` — [setSynchronizedSourceDiffPolicy](https://docs.gloo.com/forge/reference/http-api/knowledge/set-source-diff-policy.md) — sets when a source's changes wait for review
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-diff` — [approveSynchronizedSourceDiff](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-diff.md) — approves a reviewed diff, or resumes a failed apply
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/reject-diff` — [rejectSynchronizedSourceDiff](https://docs.gloo.com/forge/reference/http-api/knowledge/reject-source-diff.md) — stops a run's diff
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-shrink` — [approveSynchronizedSourceShrink](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-shrink.md) — releases the deletions a run's shrink guard holds
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/override-shrink` — [overrideSynchronizedSourceShrink](https://docs.gloo.com/forge/reference/http-api/knowledge/override-source-shrink.md) — lowers one run's shrink threshold
* `POST /api/v3/knowledge-cases` — [createKnowledgeCase](https://docs.gloo.com/forge/reference/http-api/knowledge/create-case.md) — writes a new case into a writable namespace (HTTP 201)
* `PATCH /api/v3/knowledge-cases/{caseId}` — [updateKnowledgeCase](https://docs.gloo.com/forge/reference/http-api/knowledge/update-case.md) — rewrites a case at the version read; a proven case's edit is held for review
* `POST /api/v3/knowledge-cases/{caseId}/verify` — [verifyKnowledgeCase](https://docs.gloo.com/forge/reference/http-api/knowledge/verify-case.md) — attests that a readable case is still correct
* `POST /api/v3/knowledge-cases/{caseId}/set-grade` — [setKnowledgeCaseGrade](https://docs.gloo.com/forge/reference/http-api/knowledge/set-case-grade.md) — sets a readable case's grade with a reason
* `POST /api/v3/knowledge-cases/{caseId}/set-steward` — [setKnowledgeCaseSteward](https://docs.gloo.com/forge/reference/http-api/knowledge/set-case-steward.md) — sets or clears a readable case's steward and verification interval
* `POST /api/v3/knowledge-reviews/{reviewId}/decide` — [decideKnowledgeReview](https://docs.gloo.com/forge/reference/http-api/knowledge/decide-review.md) — decides one pending review item with a recorded note (see [Deciding a review item](#deciding-a-review-item))
* `POST /api/v3/knowledge-golden-sets` — [createKnowledgeGoldenSet](https://docs.gloo.com/forge/reference/http-api/knowledge/create-golden-set.md) — creates a golden set over readable namespaces (HTTP 201)
* `PATCH /api/v3/knowledge-golden-sets/{goldenSetId}` — [updateKnowledgeGoldenSet](https://docs.gloo.com/forge/reference/http-api/knowledge/update-golden-set.md) — replaces a golden set, or renames or archives one that has runs
* `POST /api/v3/knowledge-golden-sets/{goldenSetId}/run` — [runKnowledgeGoldenSet](https://docs.gloo.com/forge/reference/http-api/knowledge/run-golden-set.md) — schedules one manual eval run of an active golden set
* `PATCH /api/v3/knowledge-settings/{settingKey}` — [setKnowledgeSetting](https://docs.gloo.com/forge/reference/http-api/knowledge/set-setting.md) — changes one learning setting (`platform:manage`), recorded in the audit trail with its value before and after
* `POST /api/v3/knowledge-reembed-runs` — [startKnowledgeReembed](https://docs.gloo.com/forge/reference/http-api/knowledge/start-reembed.md) — schedules a re-embed of every namespace not on the active embeddings model

Source reads, updates and a connect's response never return configuration, cursors, external container ids, identity or group mappings, curation, trust weight or creator identity. Changing a connected source's curation, trust weight or mappings stays in the Forge Console.

`ask` uses a fixed system prompt that callers cannot override, and its token spend is attributed to the calling External App's budget.

The writes honour an `Idempotency-Key` header for an External App JWT, a platform API key and your own Personal key: a retry with the same key never writes again. It answers `409` `idempotency_result_unavailable` unless the route's current authorization policy permits disclosure of the first response. See [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md).

A request that fails inside Forge (an embeddings or model provider error, for example) answers HTTP 500 with error code `internal_error` and the usual envelope. The message names only the `requestId`, which support can trace. With an `Idempotency-Key`, a retry under the same key does not run the write again. A 500 does not prove nothing was written, so read the namespace to reconcile before starting a new logical write under a new key.

## Knowledge cases

A case is a keyed, graded piece of knowledge: a lesson an agent recorded, a policy or how-to a person wrote, a page a knowledge source synced. The `cases/*` routes give a credential what the Console knowledge page gives a person: browse and read cases, their versions, pending revision and uses, and curate them.

| Operation | Namespaces | Cases it acts on |
| - | - | - |
| `list`, `get`, `listVersions`, `getRevision`, `listUses` | Readable | Any readable case; `listVersions` and `listUses` also a deleted one |
| `create`, `update` | Writable (the case must also be readable) | A keyed case; a case synced from a source is edited in its source |
| `verify`, `setGrade`, `setSteward` | Readable | `setGrade`: any active case or pending revision. `verify` and `setSteward`: a person-curated case, not a pending revision, a retired case or a synced one |

Steward actions follow the Console's rule: a holder of `knowledge:manage` curates every case it can read, including `global` and department cases, which it cannot write. Through the API that holder may be a person's own Personal key or an External App granted `knowledge:manage`. A verification, grade, steward change or delete is recorded with the credential's attribution: a Personal key as its owner, with the key named on the audit event (`via: "personal_key"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform API key as `platform-key:<id>`. A created or edited case records who wrote it as `addKnowledge` does.

A case outside reach answers one `404 resource_missing`, whatever the reason: a malformed or missing id, a namespace the credential cannot read, a source-restricted case, a deleted case (except where the table says otherwise). A case carries its id, namespace, scope, content and source types, artifact kind, title, key, grade, tags, timestamps, `version`, success and failure counts, steward, verification interval and due time, source id and URL, and the run, node and agent that recorded it, `null` where absent. It never carries who ingested, graded, verified, deleted or archived it, its evidence or evidence notes, its RAG id, storage, content hash, source access, owning External App or home org unit. A past version never carries its content hash either. A use never names its chat session, turn or retrieval record.

### Manually importing an SOP

1. Select the explicit namespace. An organization's SOP belongs in `organization:<orgUnitId>` even if a company or team write would succeed; it is created from the Console's New artifact, which lists the organizations you may manage, and read and updated through these operations with `actingFor`. If the organization is not offered, report the refusal and correct the authority before importing.
2. Preserve the supplied authoritative Markdown. Include SOP identifier, title, source revision/date and approval status in the content. Inspect tables, escaped pipes, lists and checkboxes before writing. Resolve broken source text with its owner; do not infer missing cells.
3. Use a stable key such as `sop.abs-002`, without a version number. Check it with `getKnowledgeCase({namespace,key})`; ranked search and an empty list page cannot prove absence. A same-key create still enforces uniqueness transactionally. For an existing case, compare first and update by ID with its current `expectedVersion`.
4. Create with `artifactKind: "how_to"` and a distinct idempotency key per intended write. A retry after an unknown outcome reuses the same key and body. Cases begin `provisional`; source approval does not automatically make a Forge case `proven`.
5. Each content field is at most 20,000 characters. Split longer SOPs at section boundaries into independently identifiable sections with stable keys, such as `sop.abs-001.access-approval`. Keep each section within the limit and include its parent SOP ID and revision. Avoid ordinal keys that shift when a section is inserted. Splits are separate writes, so record every part and its result; there is no atomic multi-part import.
6. Read every resulting case back in full. Compare with the submitted Markdown, accounting for Forge's redaction; check table cells, escaped pipes, numbering, checkboxes and the final lines. `textTruncated: true` means verification is incomplete. A search excerpt is never a full-text comparison. Record IDs, keys, namespace, versions, write outcomes and any discrepancies.
7. Search with a question answered by the SOP, acting for the organization (`actingFor`). Search again acting for a different organization, and without `actingFor`, and verify that both exclude the imported SOP. A selected-context search does not prove the deployed ticket workflow resolves its organization correctly; qualify that workflow separately before relying on it.

Existing company-wide SOPs with obsolete IDs need a source/version comparison before any migration or retirement. Renaming or adding an organization's case does not remove an older company case from retrieval.

## Knowledge records

A record is a typed fact. A synchronized record belongs to a knowledge source; an authored record belongs to a Forge-owned record collection. Each record has a `kind`, an `externalId` unique within its owner and kind, typed `attributes`, an optional `parentExternalId`, and `refs` to other records. Synchronized records carry `sourceId`, `sourceUrl`, `sourceVersion` and `verifiedAt`. Authored records carry `collectionId`, `sourceVersion` and a positive numeric `version`. Neither branch carries its entry id, namespace or storage. See [Authored knowledge records](https://docs.gloo.com/forge/knowledge/external-sources.md#authored-records).

A kind from a source is complete when all of these hold:

* a sync pass has been verified;
* the provider's checks for the kind passed;
* no item of the kind is quarantined;
* the source is not sealed;
* the last verification is no older than the source allows (48 hours by default).

When only the age fails, the kind is stale. [`records/list`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-records) answers a complete list or refuses, and checks every reference on every read. [`records/get`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-record) answers one record with its status. A search can be narrowed to records with `getChunks`' `form: "record"`, but search is ranked and partial: to read every record of a kind, list it.

## Review queue and Learning feed

The review queue holds what needs a steward's judgment: a case that earned `proven` and waits for approval, a contested or stale case, two cases that conflict or duplicate each other, a case due for verification. The Learning feed lists what the knowledge base learned: cases created, promoted from memory, replaced, moved, deleted, regraded and merged.

`listReviews`, `getReview` and `listLearning` are read at the **deployment root**: the credential must hold `knowledge:read` there (a platform grant, or the root-org-unit grant every migrated key holds). A credential that holds it only on a team or other org unit answers `403 permission_denied` with `requiredPermission: "knowledge:read"`. Rows are then limited to the credential's readable namespaces (see [Scope resolution](#scope-resolution)), and a source-restricted item or case is never returned, even to your own Personal key.

A review item names its `kind`, `status`, `reason`, `namespace`, `scopeType`, `createdAt` and `reviewedAt`, its `case` and up to five `related` cases that the credential can read (each with `entryId`, `title`, `caseKey`, `grade`, `status`, `namespace`, `successCount` and `failureCount`, `null` where absent). It never names the reviewer, the reviewer's note, the assignee, the run or the decision. A Learning item never names who acted, the agent, the run or the reason.

**A holder of `knowledge:manage` decides an item with `POST /api/v3/knowledge-reviews/{reviewId}/decide` (MCP `forge_decide_knowledge_review`), or a person in Console through the item's `handoff` link.** Every pending item carries a `handoff`, the Console path:

```json theme={null}
{
  "kind": "console",
  "decidedBy": "person",
  "item": "knowledge_review:<itemId>",
  "path": "/knowledge/review?item=<itemId>",
  "url": "https://<console>/knowledge/review?item=<itemId>",
  "requiredPermission": "knowledge:manage"
}
```

`url` is `null` when the deployment does not name its Console. A resolved item has `handoff: null`. The handoff is unchanged by the API decision route: `decidedBy: "person"` describes the Console path it opens. Bulk decisions stay in the Console review queue, which keeps each item's result when a bulk decision partly fails; the API decides one item per call.

### Deciding a review item

`POST /api/v3/knowledge-reviews/{reviewId}/decide` with `{ id, decision, note }` decides one pending item, as a steward decides it in Console. It needs `knowledge:manage`. The decision is `set_grade`, `merge`, `verify` or `dismiss`, as the item's kind allows; `note` is 1–500 characters and recorded with it. The item becomes `approved` (a grade, merge or verification) or `rejected` (dismissed).

An authorized call is a steward decision recorded with the credential's attribution, as a verification is; the stamp is never returned, and a Personal key acts as its owner. The item must be pending and in the credential's readable namespaces, read as no one, so a source-restricted item is never decided, and the item's case and every case the decision writes must be readable now. A `verify` also needs `knowledge:manage` at the case's home org unit. See [Decide a review item](https://docs.gloo.com/forge/reference/http-api/knowledge/decide-review.md) for the decisions each kind allows and the errors.

## Retrieval golden sets

A golden set measures retrieval quality, as the Console Knowledge › Quality page does: each case is a query and the golden keys (case keys, or a synced entry's source id) a good retrieval returns for it, searched in the set's namespaces. A run records recall\@k, mean reciprocal rank, each case's score and the golden keys it retrieved. A run is judged against its baseline, the first `ok` run with the same embedding, chunker version, ranking version and `k`, and `regressedFromBaseline` flags a run that fell below it.

| Operation | Scope | What it does |
| - | - | - |
| [`goldenSets/list`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-golden-sets) | `knowledge:read` | The newest 50 active sets (and 50 archived with `includeArchived=true`), each with its newest run and baselines |
| [`goldenSets/listRuns`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-golden-set-runs) | `knowledge:read` | One set's runs, newest first, a page at a time (`limit` 1–100, default 20) |
| [`goldenSets/create`](https://docs.gloo.com/forge/reference/http-api/knowledge/create-golden-set) | `knowledge:manage` | A new set: 1–50 readable namespaces and 1–100 cases (HTTP 201) |
| [`goldenSets/update`](https://docs.gloo.com/forge/reference/http-api/knowledge/update-golden-set) | `knowledge:manage` | A full replacement; a set with runs keeps its namespaces and cases (`409`), and archiving stops scheduled runs |
| [`goldenSets/run`](https://docs.gloo.com/forge/reference/http-api/knowledge/run-golden-set) | `knowledge:manage` | Schedules one `manual` run at `k` 1–20 (default 8); refused for an archived set or within a minute of the last run |

A golden set is visible only when the credential can read **every** namespace it searches, because a run's retrieved keys reveal content keys from all of them. Namespaces resolve from the credential, never the request; a Personal key acts as its owner. A set outside reach answers `404 resource_missing`, and a `namespace` filter or body namespace the credential cannot read answers `403`, recorded. A set never names who created it, and a run never returns the embeddings URL it measured.

## Knowledge sources

A knowledge source syncs one container in an external system, such as a wiki space, into cases in one scope (see [External knowledge sources](https://docs.gloo.com/forge/knowledge/external-sources.md)). Live search is retired; source response DTOs may still carry the historical `live` mode for compatibility. The `synchronized-sources/*` routes give a credential what the Console Knowledge › Synchronized sources page gives a person.

The canonical routes are `/api/v3/knowledge-synchronized-sources` (at v2, `/api/v2/knowledge/synchronized-sources/*`). The former
`/api/v2/knowledge/sources/*` compatibility aliases have been retired. Persisted retries still use
their original idempotency identity.

| Operation | Scope | What it does |
| - | - | - |
| [`synchronized-sources/list`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-sources), [`synchronized-sources/get`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source), [`synchronized-sources/listRuns`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-runs) | `knowledge:read` | Read sources and their runs in readable namespaces |
| [`synchronized-sources/listProviders`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-providers) | `knowledge:manage` and `credentials:use` | The registered providers a source can be connected through: key, label and declared modes |
| [`synchronized-sources/listContainers`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-source-containers) | `knowledge:manage` and `credentials:use` | The containers a new source at a writable target could read, by label |
| [`synchronized-sources/getKindStates`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-kind-states) | `knowledge:read` | A readable source's kinds: completeness, failing conditions, verification and record counts |
| [`synchronized-sources/create`](https://docs.gloo.com/forge/reference/http-api/knowledge/create-source) | `knowledge:manage` and `credentials:use` | Connects a source to a writable target scope (HTTP 201) |
| [`synchronized-sources/update`](https://docs.gloo.com/forge/reference/http-api/knowledge/update-source) | `knowledge:manage` | Renames, retimes, pauses or resumes a source |
| [`synchronized-sources/requestSync`](https://docs.gloo.com/forge/reference/http-api/knowledge/request-source-sync) | `knowledge:manage` | Asks a source to sync now |
| [`synchronized-sources/relist`](https://docs.gloo.com/forge/reference/http-api/knowledge/relist-source) | `knowledge:manage` | Clears a source's cursor so its next run lists every item again |
| [`synchronized-sources/remove`](https://docs.gloo.com/forge/reference/http-api/knowledge/remove-source) | `knowledge:manage` | Removes a source and permanently deletes every case it wrote |
| [`synchronized-sources/diff`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-diff), [`synchronized-sources/reviewDiff`](https://docs.gloo.com/forge/reference/http-api/knowledge/review-source-diff) | `knowledge:read` | Read a source's diff state and review a run's held changes (a Personal key) |
| [`synchronized-sources/setDiffPolicy`](https://docs.gloo.com/forge/reference/http-api/knowledge/set-source-diff-policy), [`approveDiff`](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-diff), [`rejectDiff`](https://docs.gloo.com/forge/reference/http-api/knowledge/reject-source-diff), [`approveShrink`](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-shrink), [`overrideShrink`](https://docs.gloo.com/forge/reference/http-api/knowledge/override-source-shrink) | `knowledge:manage` | Set the diff policy and decide a run's held changes (a Personal key) |

Connecting a source needs both `knowledge:manage` and `credentials:use`, and the credential's scopes must reach both: a source never stores a credential, and syncs with the credential on its vendor's connection that resolves along its target scope. The Console asks for the same pair where the source writes. The target must be in the caller's **writable** namespaces (see [Scope resolution](#scope-resolution)); a `department` or `global` namespace never is through the API. A target outside that set answers `403 forbidden`, recorded. A source outside the writable set answers one `404 resource_missing` from `remove` and `relist`.

A connect, an update, a sync request, a removal and a re-list are recorded with the credential's attribution, as a case write is: the owner of a Personal key with the key named, the External App, or the platform API key. Each new `Idempotency-Key` on `relist` re-lists again; a retry under the same key does not. A removal of a source already being removed restarts its purge and records nothing more.

### Reviewing a source's held changes

A source's diff policy can hold a run's changes for review, and its shrink guard holds deletions when a listing loses more of a kind than its threshold. A person reviews and decides them: these routes admit only a Personal key, which acts as its owner, and answer an External App or platform API key with `403 forbidden`. The owner must hold the permission where the source lives; the key's `knowledge:manage` there decides `canManage` and the review's decide flags.

1. [Read the diff state](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-diff.md) for a run in phase `held`.
2. [Review its diff](https://docs.gloo.com/forge/reference/http-api/knowledge/review-source-diff.md) page by page until the outcome is `ready`.
3. [Approve](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-diff.md) at that page's `revision` and `reviewId`, or [reject](https://docs.gloo.com/forge/reference/http-api/knowledge/reject-source-diff.md) it.

A shrink guard is decided at its revision: `shrinkGuards` in the [diff state](https://docs.gloo.com/forge/reference/http-api/knowledge/get-source-diff.md) lists each recent run's guard, with or without a diff, and a run's review gives it as `view.shrink.revision` ([approveShrink](https://docs.gloo.com/forge/reference/http-api/knowledge/approve-source-shrink.md), [overrideShrink](https://docs.gloo.com/forge/reference/http-api/knowledge/override-source-shrink.md)).

## Settings and re-embed

The learning settings decide how knowledge learns from outcomes: grade weights, proven thresholds, signal precedence, rating bands, distillation, staleness, plus the chat message to long-term memory threshold. They are deployment-wide, as on the Console Knowledge › Settings page.

| Operation | Scope | What it does |
| - | - | - |
| [`settings/get`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-settings) | `knowledge:read` | The settings in force, which keys carry a stored value, and when each was last written |
| [`settings/set`](https://docs.gloo.com/forge/reference/http-api/knowledge/set-setting) | `platform:manage` | Stores one setting its rule accepts and answers the settings after; a value its rule refuses answers 400 and writes nothing |
| [`reembed/start`](https://docs.gloo.com/forge/reference/http-api/knowledge/start-reembed) | `knowledge:manage` | Schedules a re-embed of every namespace embedded under another model than the active one |
| [`reembed/getLatestRun`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-reembed-run) | `knowledge:read` | The newest re-embed run's progress, without its error text or starter |
| [`scopes/list`](https://docs.gloo.com/forge/reference/http-api/knowledge/list-scopes) | `knowledge:read` | Every knowledge scope the credential can read or write, with whether it may write each |
| [`scopes/get`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-scope) | `knowledge:read` | One readable scope with its counts by content type and its record kinds; `meta.partial` marks a bounded read |

Every learning-setting change, from the Console or the API, records a `platform_setting_set` audit event with the value before and after. `platform:manage` is an approve-and-administer scope that a Forge agent is never granted. While Forge is stopped by an operator ([kill switch](https://docs.gloo.com/forge/run/trust-fabric.md#emergency-stops)), `settings/set`, `reembed/start` and every other knowledge write answer `403 operator_stopped`; reads continue.

The embeddings model has no knowledge route: [knowledge health](#knowledge-health) reports each namespace's model and staleness, and [`GET /api/v3/capabilities/embeddings`](https://docs.gloo.com/forge/reference/http-api/capabilities/get) the provider in force. Changing the model, and the model catalog, stays with Gloo staff.

## Adding an entry

`addKnowledge` takes `content` (required, at most 1,000,000 characters), the legacy `contentType` (`document`, `note` or `snippet`), and the optional `artifactKind`, `title` (at most 500 characters), `tags`, `scopeType`, `scopeId` and `externalRef` (at most 500 characters). Content over the cap answers HTTP 413 `payload_too_large`; split a larger document, for example at a top-level heading. An invalid `artifactKind` or any other field over its limit answers 400.

* **`artifactKind`**: the authored kind, independent of `contentType`. Allowed values are `lesson`, `policy`, `how_to`, `reference`, `faq`, and `note`. Omit it when the kind is unknown; the entry remains unclassified. Existing entries and imports that omit it stay unclassified. For example, a policy from Notion can have `contentType: "document"` and `artifactKind: "policy"`.

* **`tags`**: at most 20 labels of 1–64 characters each. They are trimmed, de-duplicated and stored on the entry, redacted like its title, and `getKnowledge` and `getChunks` return them.

* **`externalRef`**: your own record id, returned as a chunk's `source.ref`. It is also the add's de-duplication key. When an active entry added by the same caller (the same External App, or any platform API key or Personal key) already holds that `externalRef` in the target namespace, nothing is written and the call answers HTTP 200 with `{ "id": "<existing id>", "status": "active", "deduplicated": true }`. Two adds racing past that check can both write, so send an `Idempotency-Key` to make a retry safe.

A new entry answers HTTP 201 with `{ "id": "<entryId>", "status": "active" }`.

The target namespace is checked against the caller's writable set when the request arrives and again in the transaction that saves the entry. The second check resolves the set afresh: the caller's scopes from its app, org unit or key owner, and `company` from the credential's current role grants (`knowledge:manage`, narrowed by its scopes), not from the first check. If the namespace leaves the set in between (for example, `knowledge:manage` is revoked while the content is embedded), nothing is stored and the call answers the same HTTP 403 as the first check. `cases/create` and `cases/update` re-check the same way.

## Reading an entry

`POST /api/v3/knowledge-entries/{entryId}/lookup` takes the entry's `id` in the path, the `id` that `getChunks` and `addKnowledge` return. It answers a `KnowledgeEntry`: `id`, `namespace`, `contentType`, `sourceType`, `createdAt`, the optional `artifactKind`, `title`, `caseKey`, `grade`, `runId`, `nodeId`, `agentId` and `tags`, plus `text` and `textTruncated`.

`text` is the entry's inline content when it has one. Otherwise it is the entry's indexed chunks joined in order, capped at 50 chunks; `textTruncated` is `true` when the entry has more.

The entry must be active and in the caller's readable namespaces. A missing id, an entry in another namespace, and a deleted entry all answer HTTP 404 `resource_missing`, so a caller cannot tell whether an entry it cannot read exists.

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/knowledge-entries/kg2def.../lookup" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Knowledge health

`GET /api/v3/knowledge-health` returns the health projection the Console's Knowledge › Health page shows, for the knowledge the credential can read. It is computed over the caller's readable namespaces (see [Scope resolution](#scope-resolution)), or over the one readable namespace the optional `namespace` query parameter names, and read as no person, like every knowledge read through the API. A `namespace` outside the readable set answers HTTP 403 `forbidden`.

Each section of the response names its `scope`:

| Section | Scope | What it reports |
| - | - | - |
| `pending` | `readable` | Active entries still waiting for their embedding, oldest first (at most 25), with `total` read. Each is its `entryId`, `namespace` and `createdAt`: no title or case key. An entry restricted to named people is left out. |
| `sources` | `readable` | Stopped, paused and failing knowledge sources: `id`, `name`, `providerKey`, `namespace`, `targetScopeType`, `mode`, `status`, `syncIntervalMinutes`, `lastSyncAt`, `nextSyncAt`, `lastFullListAt`, `consecutiveFailures` and `lastError`, redacted. A source's configuration, cursor, group mappings and creator are never returned. |
| `sourceItems` | `readable` | Items a sync source failed to sync, newest failure first, with `attempts` and `quarantined`. An item whose case the caller may not read is `restricted: true` with `lastError: null`. No case key is returned. |
| `embeddings` | `readable` | For up to 50 namespaces, the model of its ready embedding version and whether it is `stale` against the latest re-embed run's target model. |
| `syncLag` | `readable` | How many active sources are overdue to sync, and the oldest due time. |
| `quality` | `readable` | How many review items wait for a decision (`openReviewItems`); an item on a restricted case is not counted. |
| `reembed` | `deployment` | The latest re-embed run's progress (`latestRun`, or `null`): status, target model, namespace and entry counts, `failedInReadable` (its failed entries kept in the caller's readable namespaces) and `hasError`. Its error text and who started it are withheld: the error may name another tenant's namespace. |
| `integrity` | `deployment` | The knowledge integrity audit's current lap (`lap`, or `null`). |
| `sweeps` | `deployment` | Each knowledge cron's newest run and newest recent failure, without error text. |
| `settings` | `deployment` | The learning settings in force, the chat long-term memory threshold, and which settings carry a stored value: the same view [`settings/get`](https://docs.gloo.com/forge/reference/http-api/knowledge/get-settings) returns. Change one with [`settings/set`](https://docs.gloo.com/forge/reference/http-api/knowledge/set-setting) (see [Settings and re-embed](#settings-and-re-embed)). |

Every list is bounded and says `truncated` when the bounded read stopped before reading everything, so a count is then a lower bound.

### Remedies

Two of the repairs the Console's Health page offers are these remedies, both under `knowledge:manage` and only for knowledge in the caller's **writable** namespaces (see [Scope resolution](#scope-resolution)):

* `POST /api/v3/knowledge-entries/{entryId}/retry` with `{ "entryId": "<id>" }` embeds one stuck pending entry again now and answers `{ entryId, scheduled }`. `scheduled` is `false`, and nothing is scheduled, for an entry that is no longer active or is already embedded.
* `POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync` with `{ "sourceId": "<id>" }` asks a source to sync now and answers `{ sourceId, outcome }`: `scheduled` (a run was scheduled and a `knowledge_source_sync_requested` audit event recorded, naming the caller), `running` (a run already holds the source; nothing scheduled or audited) or `inactive` (a paused or stopped source; nothing scheduled).

A missing id, a target outside the writable set, an entry restricted to named people and a source being removed answer HTTP 404 `resource_missing`. Two sync requests made before the first scheduled run starts both answer `scheduled` and are both audited; the second run finds the first holding the source and exits, so a source never syncs twice at once. With an `Idempotency-Key`, a retry of one request schedules nothing again (see [Knowledge remedy replay](https://docs.gloo.com/forge/reference/idempotency.md#knowledge-remedy-replay)).

Re-listing a source, starting a re-embed and changing a learning setting are in the API too: see [Knowledge sources](#knowledge-sources) and [Settings and re-embed](#settings-and-re-embed). So are review decisions and golden-set runs: see [Deciding a review item](#deciding-a-review-item) and [Retrieval golden sets](#retrieval-golden-sets).

```bash theme={null}
curl "$FORGE_BASE/api/v3/knowledge-health?namespace=company" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## What is redacted

Before a knowledge entry is chunked and embedded, Forge replaces secrets, payment card numbers and US Social Security numbers in its text, title and summary with placeholders such as `[REDACTED_API_KEY]`, `[REDACTED_CREDIT_CARD]` and `[REDACTED_SSN]`. Secrets are provider API keys, `Bearer` tokens, JWTs and credential assignments such as `client_secret=…`. A card number is redacted only when it passes the Luhn check and is written as one digit run or in card-style groups (such as `4111 1111 1111 1111`), so a date range is kept. A reference number is kept unless it is a single 13–19 digit run that passes the Luhn check. The stored entry and its embeddings hold only the redacted text; this includes an uploaded file's name and an entry promoted from a memory. A case's evidence is redacted the same way: an outcome's note (including one an agent reports with `knowledge_report_outcome`) and the reason a person gives for a grade change, which is also redacted in the grade change's audit event. The reason given for deleting a case is redacted in its audit event too.

Email addresses and phone numbers are kept: knowledge legitimately holds contact details, such as a vendor's support address. Redaction does not refuse the write; it removes the value and logs which kinds it removed, never the content.

A case's `key` is an identifier, so it is never redacted: it is stored and looked up exactly as written. A new key that holds a secret, card number or SSN is refused with the error code `KNOWLEDGE_KEY_SENSITIVE`, which names the kinds found and never the key, and nothing is stored. A key with an email address or phone number is accepted. A case stored before this check keeps its key: it is still found by that key, and recording it again updates it.

## External App knowledge isolation

Knowledge entries ingested by an External App, including through `addKnowledge`, carry an optional `principalExternalApplicationId` field. When the owning app is deactivated, the platform deletes these entries, and the cases the app's agents recorded with `knowledge_record`, wherever they wrote them. Other entries in shared project or team corpora are never affected by app deactivation.

## Deletion

Deleting a knowledge entry removes its content. The chunks and embeddings are deleted from the vector store, so the entry can no longer be retrieved by search, `getChunks`, `ask` or `getKnowledge`. The entry's record stays as a tombstone (`status: "deleted"`, with `deletedAt` and `deletedBy` set) and its stored text is cleared, including the title of an entry promoted from a memory. Every deletion writes an audit event with resource type `knowledge_entry`.

Entries are deleted when:

* A caller with `knowledge:manage` calls `deleteKnowledge`.
* An External App deletes a file it uploaded, or the app is deactivated.
* An agent is deleted for good: the cases in its own `agent:<agentId>` namespace go with it, and until they are gone, creating an agent with the same `agentId` is refused with `AGENT_ID_KNOWLEDGE_NOT_PURGED`.
* The long-term memory an entry was promoted from is forgotten (including through `DELETE /api/v3/memory/{memoryId}`), cleared, swept for disuse, or purged by app deactivation. This applies to entries an agent or a retrieval threshold promoted. An entry a person promoted in the Console stays.

`DELETE /api/v3/knowledge-entries/{entryId}` takes the entry's `id` in the path and an optional body `{ "reason": "..." }`; `reason` is at most 500 characters, and recorded on the audit event. The entry must be in the caller's **writable** namespaces (see [Scope resolution](#scope-resolution)); `global` entries are never deletable through the API. A missing id or an entry outside the writable set answers HTTP 404. The credential must also hold `knowledge:manage` where the entry belongs (its org unit, or the deployment root for an entry without one), as a delete in the Console does; otherwise the call answers HTTP 403 `forbidden`. An External App needs no such grant to delete in its own `external_app` namespace. A case synced from a knowledge source answers HTTP 409 `conflict` and is not deleted: its source owns it, and the next sync would write it again. Remove it at the source, or remove the source. A successful call answers `{ "data": { "id": "<entryId>", "status": "deleted" } }`. Deleting an entry the caller could delete and has already deleted answers the same 200 again.

```bash theme={null}
curl -X DELETE "$FORGE_BASE/api/v3/knowledge-entries/kg2def..." \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Superseded policy document"}'
```

Search only returns active entries. Archived, pending-review and deleted entries are never returned.

## Related

* [Memory API](https://docs.gloo.com/forge/reference/http-api/memory) — forgetting a long-term memory deletes the knowledge an agent promoted from it
* [MCP Server](https://docs.gloo.com/forge/reference/mcp-server.md) — the `knowledge` tool group wraps `getChunks`, `addKnowledge`, `get`, `delete`, `export`, `health`, `retryPendingEntry`, `sources/*`, `cases/*`, the review reads, `decideReview`, `goldenSets/*`, `settings/*`, `reembed/*` and `scopes/*`; there is no `ask` tool
* [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md) — making `addKnowledge`, `delete`, the source writes, the case writes, review decisions, golden-set writes, setting changes and re-embeds safe to retry
* [External knowledge sources](https://docs.gloo.com/forge/knowledge/external-sources.md) — knowledge synced from other systems
* [External Apps](https://docs.gloo.com/forge/reference/http-api/externalApps) — configure scopes for your app

## Prior version history

`POST /api/v3/knowledge-snapshots/search` requires `knowledge:read`. Pass `{ "entryId": "..." }` for a case or record, `{ "sourceId": "...", "kind": "...", "externalId": "..." }` for a synchronized record, or `{ "collectionId": "...", "kind": "...", "externalId": "..." }` for an authored record. Optional `pageSize` is an integer1..20 (default20); continue with the returned opaque `nextCursor` and the same address. Unknown fields, mixed addressing, invalid page sizes and cursors answer400. A successful envelope contains `{form,versions,nextCursor?}`; every version includes its sequence, written/change times, actual change kind, actor and explicit prior snapshot. Record snapshots include attributes and any stored annotations, with the historical sourceVersion. Authored snapshots include `collectionId` and their numeric record `version`; synchronized snapshots retain `sourceId`. They do not invent a historical verification time.

The credential's current get-equivalent namespace/source access is checked on every page. Machine credentials, including owner-scoped Personal keys, remain unable to read source-restricted entries. Missing, inactive, deleted and unreadable entries share404 `resource_missing`. These POST reads execute current authorization even when an Idempotency-Key header is sent; no cached read replay is used. Pages are not a snapshot-isolation session, and a filtered page can be empty while `nextCursor` remains.

Record retention is20 prior snapshots, with no fabricated backfill. Case history preserves its superseding/discarding actor as `legacy` when only an opaque identity was stored. An optional `auditEventId` corroborates an exact version-change event among a bounded four-event lookup; it does not establish actor kind or a complete activity feed. Generic changeRunId provenance can name a workflow run. Explicit source removal erases synchronized record history and never selects authored history.

## Synchronized-source naming

Canonical source operations use `synchronized-sources`; the capability domain is `synchronized_knowledge`. Old persisted source identifiers remain compatible. [Knowledge sources](https://docs.gloo.com/forge/knowledge/external-sources.md) explains current setup and terminology. The v3 operation reference uses resource-oriented paths; the v2 request examples on this family overview describe the compatibility API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.