Skip to main content
POST
Create a knowledge record collection
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/collections/create creates an authored record collection, the Console’s “new collection”: a named kind schema in one namespace. Authored records are then written to it with records/create. MCP hosts call it through forge_call_operation with operationId createKnowledgeRecordCollection. The body is { name, namespace, schema }:
  • name: 1 to 120 characters, with no surrounding spaces;
  • namespace: one namespace in the credential’s writable set (see List knowledge scopes);
  • schema: the kind schema its records follow, with kind, displayName, searchable, titleAttribute and attributes, and optionally parentKind and refs naming kinds that the namespace or a registered provider already holds.
It needs knowledge:manage, and the credential must hold it where the namespace lives: the namespace’s org unit, or the deployment root for company. A namespace outside the writable set, or one whose home the credential does not manage, answers 403 forbidden, recorded. A kind the namespace already holds answers 409 conflict (collection_kind_exists). An invalid name or schema answers 400 bad_request. The collection is created by, and audited as, the credential:
  • an External App or platform key as its principal stamp, with the givers of the grants that allowed it;
  • a Personal key as its owner.
The response is 201 with the collection, exactly as collections/get reads it. The schema and home cannot be changed later; to change them, create a new collection. With an Idempotency-Key, a repeat of a completed request returns the recorded response without writing again, but only while the caller may still write that collection.

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

An authored record collection to create: its name (1 to 120 characters, no surrounding spaces), the namespace it lives in, which must be in the caller's writable namespaces, and the kind schema its records follow. A kind the namespace already holds is refused, and a schema whose parent kind or references name a kind the namespace or a registered provider does not hold is refused.

name
string
required
Required string length: 1 - 120
namespace
string
required
Minimum string length: 1
schema
object
required

Response

The collection created

data
object
required
meta
object
required