Skip to main content
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

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 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; 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 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 — 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 — 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 — reads one entry and its text
  • GET /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 feed
  • GET /api/v3/knowledge-reviews/{reviewId} — getReview — reads one review item
  • GET /api/v3/knowledge-learning-events — listLearning — pages what the knowledge base learned in a window of at most 90 days
  • GET /api/v3/knowledge-synchronized-sources — listSynchronizedSources — lists the newest 100 sources in readable namespaces
  • GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId} — getSynchronizedSource — reads one source without its configuration or access mappings
  • GET /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs — listSynchronizedSourceRuns — pages one readable source’s runs, newest first, with redacted errors
  • GET /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 status
  • POST /api/v3/knowledge-snapshots/search — getKnowledgeHistory — current-authorized prior versions for a case or record
  • GET /api/v3/knowledge-collections — listKnowledgeRecordCollections — lists Forge-owned record collections
  • GET /api/v3/knowledge-collections/{collectionId} — getKnowledgeRecordCollection — reads one record collection
  • POST /api/v3/knowledge-collections — createKnowledgeRecordCollection — creates a record collection in a writable namespace (knowledge:manage where it lives)
  • GET /api/v3/knowledge-subject-collections — listKnowledgeSubjectCollections — 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 — adds an authored record
  • PATCH /api/v3/knowledge-collections/{collectionId}/records/{externalId} — updateKnowledgeRecord — updates an authored record
  • DELETE /api/v3/knowledge-collections/{collectionId}/records/{externalId} — removeKnowledgeRecord — removes an authored record
  • GET /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 stewardship
  • GET /api/v3/knowledge-cases/{caseId}/versions — listKnowledgeCaseVersions — pages a case’s past versions, newest first
  • GET /api/v3/knowledge-cases/{caseId}/revision — getKnowledgeCaseRevision — reads the edit held for review on a proven case
  • GET /api/v3/knowledge-cases/{caseId}/uses — listKnowledgeCaseUses — lists the runs and chat turns that cited a case
  • GET /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 first
  • GET /api/v3/knowledge-synchronized-source-providers — listSynchronizedSourceProviders — 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 — 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 — reads a readable source’s kinds: completeness, failing conditions and record counts
  • GET /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 progress
  • GET /api/v3/knowledge-scopes — listKnowledgeScopes — lists every knowledge scope the credential can read or write, with whether it may write each
  • GET /api/v3/knowledge-scopes/{scopeId} — getKnowledgeScope — reads one readable scope with its counts by content type and the record kinds it can list
Writes:
  • POST /api/v3/knowledge-entries — addKnowledge — 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)
  • DELETE /api/v3/knowledge-entries/{entryId} — deleteKnowledge — deletes one entry in a writable namespace
  • GET /api/v3/knowledge-export — exportKnowledge — 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 — 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 now
  • PATCH /api/v3/knowledge-synchronized-sources/{synchronizedSourceId} — updateSynchronizedSource — renames, retimes, pauses or resumes one source in a writable namespace
  • POST /api/v3/knowledge-synchronized-sources — createSynchronizedSource — connects a source to a writable scope (HTTP 201; knowledge:manage and credentials: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 wrote
  • POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist — relistSynchronizedSource — re-lists one source in a writable namespace from the start
  • POST /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 review
  • POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-diff — approveSynchronizedSourceDiff — approves a reviewed diff, or resumes a failed apply
  • POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/reject-diff — rejectSynchronizedSourceDiff — stops a run’s diff
  • POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-shrink — approveSynchronizedSourceShrink — releases the deletions a run’s shrink guard holds
  • POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/override-shrink — overrideSynchronizedSourceShrink — lowers one run’s shrink threshold
  • POST /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 review
  • POST /api/v3/knowledge-cases/{caseId}/verify — verifyKnowledgeCase — attests that a readable case is still correct
  • POST /api/v3/knowledge-cases/{caseId}/set-grade — setKnowledgeCaseGrade — sets a readable case’s grade with a reason
  • POST /api/v3/knowledge-cases/{caseId}/set-steward — setKnowledgeCaseSteward — sets or clears a readable case’s steward and verification interval
  • POST /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 runs
  • POST /api/v3/knowledge-golden-sets/{goldenSetId}/run — runKnowledgeGoldenSet — schedules one manual eval run of an active golden set
  • PATCH /api/v3/knowledge-settings/{settingKey} — setKnowledgeSetting — changes one learning setting (platform:manage), recorded in the audit trail with its value before and after
  • POST /api/v3/knowledge-reembed-runs — startKnowledgeReembed — 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. 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. 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. 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 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 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), 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 first ok 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 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. 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 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 for a run in phase held.
  2. Review its diff page by page until the outcome is ready.
  3. Approve at that page’s revision and reviewId, or reject it.
A shrink guard is decided at its revision: 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 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.

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 under knowledge:manage and only for knowledge in the caller’s writable namespaces (see 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). 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 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); 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.
Search only returns active entries. Archived, pending-review and deleted entries are never returned.
  • Memory API — forgetting a long-term memory deletes the knowledge an agent promoted from it
  • MCP Server — 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 — 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 use synchronized-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.