Skip to main content
PATCH
Edit a knowledge case
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/cases/update rewrites a case’s title and Markdown content, as a person does from the Console. It needs knowledge:manage. The body is { entryId, expectedVersion, title, content, artifactKind? }, with the same bounds as create. expectedVersion is the version from Get a knowledge case: a case that has moved on since answers 409 conflict, and nothing is written. The case must be readable by the credential and in a namespace it can write (else 403). A pending revision’s id, or an entry that is not a keyed case, answers 400. A case synced from a knowledge source answers 409 conflict: edit it in its source. A malformed, missing, deleted, unreadable or source-restricted case answers 404 resource_missing. An edit never marks a case as an External App’s own. Send an Idempotency-Key to retry safely; see Knowledge curation replay. A Personal MCP key addressing a Customer case by entryId revalidates the case’s Customer namespace, current Gloo-root authority and credential scopes. Keep the stable case key across SOP versions; use the returned version as expectedVersion. An update does not move the case between namespaces. If an edit is held as pending_review, the live case still contains its prior approved text.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (Idempotency-Replayed: true) only when the route's current authorization policy permits disclosure; otherwise 409 idempotency_result_unavailable. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

caseId
string
required
Minimum string length: 1

Body

application/json

A case's new title and Markdown content. expectedVersion is the case version the edit was based on: a case that has moved on answers 409.

expectedVersion
integer
required
title
string
required
Required string length: 1 - 200
content
string
required
Required string length: 1 - 20000
artifactKind
enum<string>
Available options:
lesson,
policy,
how_to,
reference,
faq,
note
actingFor
string

The orgUnitId of the organization the edit acts for: it needs knowledge:manage at that organization's own unit or at platform scope. Absent, only Gloo's cases are edited.

Required string length: 1 - 200

Response

What the edit did

data
object
required

What one case write did: created a case, updated it in place, left it unchanged (the same title and text), or held an edit of a proven case as its pending revision for review (pending_review: entryId is the revision and revisionOf the proven case; else revisionOf is null).

meta
object
required