Skip to main content
POST
Create 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/create writes a case, graded provisional, as a person does from the Console knowledge page. It needs knowledge:manage, and answers 201 with { entryId, outcome: "created", revisionOf: null }. A live case with the same key in the namespace answers 409 conflict: edit that case instead. A write that lands on the key while this one is saved also answers 409, and nothing is overwritten. An External App’s case is its own: it is deleted when the app is deactivated. For a Customer SOP, a person’s own key or a platform key can supply namespace: "customer:<canonicalCustomerId>", which acts for the Customer’s organization and needs knowledge:manage there; see Selecting a Customer’s partition. Authority and the active Customer/Organization link are checked again inside the final save. An unavailable Customer is refused; the write never falls back to company. Check the exact namespace/key with Get case before creating, and read back the stored text afterward. Send an Idempotency-Key to retry safely. A completed 201 is replayed only while the case is still active and readable by the credential; otherwise the repeat answers 409 idempotency_result_unavailable. See Knowledge curation replay.

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

Body

application/json

A new case: its scope (namespace, one the caller may write), title (1–200 characters), Markdown content (1–20,000 characters), an optional key (1–200 characters, never an ext: source key; omitted, the case is keyed by its title and content) and an optional artifact kind. The case is graded provisional.

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

Response

The case was created

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