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.
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
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.
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 incompany. 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-scopeslists each organization the caller may act for, withscopeTypeorganizationand itsorgUnitIdasentityId. Pass that id asactingFor.- A refused
actingForanswers 403forbidden; 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/listtakesactingFororcollectionId, not both. Subject collections and record collections are selected by namespace, as before.- A read by id without
actingForreads only Gloo’s knowledge: an organization’s case or entry answers 404, as any entry outside reach does.
Selecting a Customer’s partition
While an organization’s knowledge moves into its own partition, some of it is still in its linked Customer’scustomer:<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; 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) andsetKnowledgeSetting(platform:manage) answer403 forbiddento 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.
verifyKnowledgeCaseandsetKnowledgeCaseStewardneedknowledge:manageat the case’s org unit (else the deployment root), asdeletedoes; an External App’s own namespace is its own. - A source is connected where it writes.
createSynchronizedSourceneedsknowledge:manageandcredentials:useat the target’s home: the company root for acompanysource, 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 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.
getKnowledgeRecordandgetKnowledgeHistoryneed the app’sknowledge:readat the record’s source home, aslistKnowledgeRecordsdoes.
Operations
Reads:POST /api/v3/knowledge-chunks/search— getChunks — vector and text search over every namespace the request reads, fused by rank; returns the top-N chunks (topK, 1–50, default 10;formnarrows tocaseorrecord), each with a rankscorein (0, 1] and, when the vector search found it, its cosinesimilarity; no LLM synthesis. A recorded case’s chunk also carries itsgrade(provisional,provenorcontested); aretiredcase is never returnedPOST /api/v3/knowledge/ask— ask — retrieves the 5 most relevant chunks and answers from those whose cosinesimilarityis 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 andmodel"none", and calls no model. The floor is an interim value that has not yet been measured against production dataPOST /api/v3/knowledge-entries/{entryId}/lookup— getKnowledge — reads one entry and its textGET /api/v3/knowledge-health— getKnowledgeHealth — what is broken in the knowledge the caller can read, and how far behind it is (see Knowledge health)GET /api/v3/knowledge-reviews— listReviews — pages the review queue; see Review queue and Learning feedGET /api/v3/knowledge-reviews/{reviewId}— getReview — reads one review itemGET /api/v3/knowledge-learning-events— listLearning — pages what the knowledge base learned in a window of at most 90 daysGET /api/v3/knowledge-synchronized-sources— listSynchronizedSources — lists the newest 100 sources in readable namespacesGET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}— getSynchronizedSource — reads one source without its configuration or access mappingsGET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs— listSynchronizedSourceRuns — pages one readable source’s runs, newest first, with redacted errorsGET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/diff— getSynchronizedSourceDiff — reads one source’s diff policy and its runs’ review phases (a Personal key; see Reviewing a source’s held changes)POST /api/v3/knowledge-records/search— listKnowledgeRecords — every record of the requested kinds, complete or refused, in pages of 500 (see Knowledge records)POST /api/v3/knowledge-records/lookup— getKnowledgeRecord — reads one record and its statusPOST /api/v3/knowledge-snapshots/search— getKnowledgeHistory — current-authorized prior versions for a case or recordGET /api/v3/knowledge-collections— listKnowledgeRecordCollections — lists Forge-owned record collectionsGET /api/v3/knowledge-collections/{collectionId}— getKnowledgeRecordCollection — reads one record collectionPOST /api/v3/knowledge-collections— createKnowledgeRecordCollection — creates a record collection in a writable namespace (knowledge:managewhere it lives)GET /api/v3/knowledge-subject-collections— listKnowledgeSubjectCollections — lists the subject collections you read, with readable artifact counts; list one collection’s artifacts withGET /api/v3/knowledge-cases?collectionId=POST /api/v3/knowledge-collections/{collectionId}/records— createKnowledgeRecord — adds an authored recordPATCH /api/v3/knowledge-collections/{collectionId}/records/{externalId}— updateKnowledgeRecord — updates an authored recordDELETE /api/v3/knowledge-collections/{collectionId}/records/{externalId}— removeKnowledgeRecord — removes an authored recordGET /api/v3/knowledge-cases— listKnowledgeCases — pages the readable cases, filtered and sorted as the Console knowledge list (see Knowledge cases)GET /api/v3/knowledge-case-lookup— getKnowledgeCase — reads one case, its text, version and stewardshipGET /api/v3/knowledge-cases/{caseId}/versions— listKnowledgeCaseVersions — pages a case’s past versions, newest firstGET /api/v3/knowledge-cases/{caseId}/revision— getKnowledgeCaseRevision — reads the edit held for review on a proven caseGET /api/v3/knowledge-cases/{caseId}/uses— listKnowledgeCaseUses — lists the runs and chat turns that cited a caseGET /api/v3/knowledge-golden-sets— listKnowledgeGoldenSets — lists the retrieval golden sets whose every namespace the credential can read, each with its newest run and baselines (see Retrieval golden sets)GET /api/v3/knowledge-golden-sets/{goldenSetId}/runs— listKnowledgeGoldenSetRuns — lists one golden set’s eval runs, newest firstGET /api/v3/knowledge-synchronized-source-providers— listSynchronizedSourceProviders — lists the providers a source can be connected through (knowledge:manageandcredentials:use)POST /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers— listSynchronizedSourceContainers — lists the containers a new source at a writable target could read (knowledge:manageandcredentials:use)GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/kind-states— getSynchronizedSourceKindStates — reads a readable source’s kinds: completeness, failing conditions and record countsGET /api/v3/knowledge-settings— getKnowledgeSettings — reads the deployment’s learning settings in force (see Settings and re-embed)GET /api/v3/knowledge-reembed-latest-run— getLatestKnowledgeReembedRun — reads the newest re-embed run’s progressGET /api/v3/knowledge-scopes— listKnowledgeScopes — lists every knowledge scope the credential can read or write, with whether it may write eachGET /api/v3/knowledge-scopes/{scopeId}— getKnowledgeScope — reads one readable scope with its counts by content type and the record kinds it can list
POST /api/v3/knowledge-entries— addKnowledge — ingestsdocument,noteorsnippetcontent into one writable namespace; answers HTTP 201, or 200 when theexternalRefwas already added (see Adding an entry)DELETE /api/v3/knowledge-entries/{entryId}— deleteKnowledge — deletes one entry in a writable namespaceGET /api/v3/knowledge-export— exportKnowledge — returns a 24-hour download URL for NDJSON from one readable namespace: its active entries, and withincludeDeleted=trueits tombstones as metadata onlyPOST /api/v3/knowledge-entries/{entryId}/retry— retryKnowledgeEntry — embeds one stuck pending entry in a writable namespace again now (see Remedies)POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync— requestSynchronizedSourceSync — asks one source in a writable namespace to sync nowPATCH /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}— updateSynchronizedSource — renames, retimes, pauses or resumes one source in a writable namespacePOST /api/v3/knowledge-synchronized-sources— createSynchronizedSource — connects a source to a writable scope (HTTP 201;knowledge:manageandcredentials:use, see Knowledge sources)DELETE /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}— removeSynchronizedSource — removes one source in a writable namespace and permanently deletes every case it wrotePOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist— relistSynchronizedSource — re-lists one source in a writable namespace from the startPOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/review-diff— reviewSynchronizedSourceDiff — 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 — sets when a source’s changes wait for reviewPOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-diff— approveSynchronizedSourceDiff — approves a reviewed diff, or resumes a failed applyPOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/reject-diff— rejectSynchronizedSourceDiff — stops a run’s diffPOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-shrink— approveSynchronizedSourceShrink — releases the deletions a run’s shrink guard holdsPOST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/override-shrink— overrideSynchronizedSourceShrink — lowers one run’s shrink thresholdPOST /api/v3/knowledge-cases— createKnowledgeCase — writes a new case into a writable namespace (HTTP 201)PATCH /api/v3/knowledge-cases/{caseId}— updateKnowledgeCase — rewrites a case at the version read; a proven case’s edit is held for reviewPOST /api/v3/knowledge-cases/{caseId}/verify— verifyKnowledgeCase — attests that a readable case is still correctPOST /api/v3/knowledge-cases/{caseId}/set-grade— setKnowledgeCaseGrade — sets a readable case’s grade with a reasonPOST /api/v3/knowledge-cases/{caseId}/set-steward— setKnowledgeCaseSteward — sets or clears a readable case’s steward and verification intervalPOST /api/v3/knowledge-reviews/{reviewId}/decide— decideKnowledgeReview — decides one pending review item with a recorded note (see Deciding a review item)POST /api/v3/knowledge-golden-sets— createKnowledgeGoldenSet — creates a golden set over readable namespaces (HTTP 201)PATCH /api/v3/knowledge-golden-sets/{goldenSetId}— updateKnowledgeGoldenSet — replaces a golden set, or renames or archives one that has runsPOST /api/v3/knowledge-golden-sets/{goldenSetId}/run— runKnowledgeGoldenSet — schedules one manual eval run of an active golden setPATCH /api/v3/knowledge-settings/{settingKey}— setKnowledgeSetting — changes one learning setting (platform:manage), recorded in the audit trail with its value before and afterPOST /api/v3/knowledge-reembed-runs— startKnowledgeReembed — schedules a re-embed of every namespace not on the active embeddings model
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.
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. Thecases/* 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.
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
- 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 withactingFor. If the organization is not offered, report the refusal and correct the authority before importing. - 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.
- Use a stable key such as
sop.abs-002, without a version number. Check it withgetKnowledgeCase({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 currentexpectedVersion. - 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 beginprovisional; source approval does not automatically make a Forge caseproven. - 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. - 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: truemeans verification is incomplete. A search excerpt is never a full-text comparison. Record IDs, keys, namespace, versions, write outcomes and any discrepancies. - Search with a question answered by the SOP, acting for the organization (
actingFor). Search again acting for a different organization, and withoutactingFor, 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.
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 akind, 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.
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).
records/list answers a complete list or refuses, and checks every reference on every read. records/get 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 earnedproven 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), 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:
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 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 firstok run with the same embedding, chunker version, ranking version and k, and regressedFromBaseline flags a run that fell below it.
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). Live search is retired; source response DTOs may still carry the historicallive 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.
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); 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 with403 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.
- Read the diff state for a run in phase
held. - Review its diff page by page until the outcome is
ready. - Approve at that page’s
revisionandreviewId, or reject it.
shrinkGuards in the diff state lists each recent run’s guard, with or without a diff, and a run’s review gives it as view.shrink.revision (approveShrink, overrideShrink).
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.
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), settings/set, reembed/start and every other knowledge write answer 403 operator_stopped; reads continue.
The embeddings model has no knowledge route: knowledge health reports each namespace’s model and staleness, and GET /api/v3/capabilities/embeddings 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 ofcontentType. Allowed values arelesson,policy,how_to,reference,faq, andnote. 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 havecontentType: "document"andartifactKind: "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, andgetKnowledgeandgetChunksreturn them. -
externalRef: your own record id, returned as a chunk’ssource.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 thatexternalRefin 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 anIdempotency-Keyto make a retry safe.
{ "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.
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), 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:
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 underknowledge:manage and only for knowledge in the caller’s writable namespaces (see Scope resolution):
POST /api/v3/knowledge-entries/{entryId}/retrywith{ "entryId": "<id>" }embeds one stuck pending entry again now and answers{ entryId, scheduled }.scheduledisfalse, and nothing is scheduled, for an entry that is no longer active or is already embedded.POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-syncwith{ "sourceId": "<id>" }asks a source to sync now and answers{ sourceId, outcome }:scheduled(a run was scheduled and aknowledge_source_sync_requestedaudit event recorded, naming the caller),running(a run already holds the source; nothing scheduled or audited) orinactive(a paused or stopped source; nothing scheduled).
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).
Re-listing a source, starting a re-embed and changing a learning setting are in the API too: see Knowledge sources and Settings and re-embed. So are review decisions and golden-set runs: see Deciding a review item and Retrieval golden sets.
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 throughaddKnowledge, 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:managecallsdeleteKnowledge. - 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 sameagentIdis refused withAGENT_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); 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.
Related
- Memory API — forgetting a long-term memory deletes the knowledge an agent promoted from it
- MCP Server — the
knowledgetool group wrapsgetChunks,addKnowledge,get,delete,export,health,retryPendingEntry,sources/*,cases/*, the review reads,decideReview,goldenSets/*,settings/*,reembed/*andscopes/*; there is noasktool - Idempotency — 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 — knowledge synced from other systems
- External Apps — 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 usesynchronized-sources; the capability domain is synchronized_knowledge. Old persisted source identifiers remain compatible. Knowledge sources 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.
