Skip to main content
POST
/
api
/
knowledge
/
knowledge-entries
Create a new knowledge entry
curl --request POST \
  --url https://{tenant}.app.big-panda.ai/api/knowledge/knowledge-entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "content": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "visibility": "public",
  "summary": "<string>",
  "layer": "<string>",
  "tags": [
    "<string>"
  ],
  "type": "knowledge",
  "language": "de",
  "metadata": {},
  "source": "manual",
  "source_reference": "<string>",
  "similarity_text": "<string>",
  "search_keywords": [
    "<string>"
  ],
  "project_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{
  "title": "<string>",
  "content": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "visibility": "public",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tenant_id": "<string>",
  "type": "knowledge",
  "version": 123,
  "language": "<string>",
  "translation_group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source": "manual",
  "source_reference": "<string>",
  "embedding_model": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "summary": "<string>",
  "layer": "<string>",
  "tags": [
    "<string>"
  ],
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "search_keywords": [
    "<string>"
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.big-panda.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API-Token aus dem Big-Panda-Admin-UI unter Einstellungen → API-Keys. Header: Authorization: Bearer <token>.

Headers

​
X-Scopes
string
default:""

Space-separated scope set from the token (ADR-015)

​
X-Audit-Source
string
default:api

Audit-channel from the gateway (M.5)

​
X-Client-Id
string | null

OAuth client_id; only set for MCP-channel calls

Body

application/json

Payload for creating a new knowledge entry.

type defaults to 'knowledge' so existing clients keep working. metadata is validated against the type-specific schema in entry_metadata.py — the validated/normalised dict overwrites the raw input so the route can persist it directly.

​
title
string
required
Required string length: 1 - 500
​
content
string
required
Minimum string length: 1
​
category_id
string<uuid>
required
​
visibility
enum<string>
required

Allowed values for the visibility field of a knowledge entry.

'personal' is ownership-gated (ADR-015 §3a): it exists in the enum so responses carrying it validate correctly, but write-side routes block it on the main path — personal entries are created via POST /knowledge-entries/personal only.

'workspace' (ROADMAP M.8) is the workspace-scoped visibility hook. Code accepts the value passively until tenants.workspaces_enabled is flipped on; today no read path filters by it.

Available options:
public,
internal,
personal,
restricted,
community,
workspace
​
summary
string | null
​
layer
string | null
Maximum string length: 50
​
tags
string[]
​
type
enum<string>
default:knowledge

Allowed values for the type discriminator (ADR-020).

Mirrors ALLOWED_TYPES in app/models/knowledge_entry.py and the DB CHECK constraint added in migration 0026. Each value selects a metadata-schema in app/schemas/entry_metadata.py.

Available options:
knowledge,
skill,
process,
glossary,
memory,
bootstrap,
skill_index
​
language
string
default:de
Required string length: 2 - 5
​
metadata
Metadata · object
​
source
enum<string>
default:manual

Where a knowledge entry originated from.

Available options:
manual,
import,
conversational,
learning_loop,
system
​
source_reference
string | null
​
similarity_text
string | null

Anchor text for 'related themes'. Bewusst kurz/prägnant: Tags + Layer + Topic-Stichworte sind typisch.

​
search_keywords
string[]

Alternative spellings/synonyms — boosts BM25 matches.

​
project_ids
string<uuid>[] | null

Response

Successful Response

Knowledge entry data returned in HTTP responses.

​
title
string
required
Required string length: 1 - 500
​
content
string
required
Minimum string length: 1
​
category_id
string<uuid>
required
​
visibility
enum<string>
required

Allowed values for the visibility field of a knowledge entry.

'personal' is ownership-gated (ADR-015 §3a): it exists in the enum so responses carrying it validate correctly, but write-side routes block it on the main path — personal entries are created via POST /knowledge-entries/personal only.

'workspace' (ROADMAP M.8) is the workspace-scoped visibility hook. Code accepts the value passively until tenants.workspaces_enabled is flipped on; today no read path filters by it.

Available options:
public,
internal,
personal,
restricted,
community,
workspace
​
id
string<uuid>
required
​
tenant_id
string
required
​
type
enum<string>
required

Allowed values for the type discriminator (ADR-020).

Mirrors ALLOWED_TYPES in app/models/knowledge_entry.py and the DB CHECK constraint added in migration 0026. Each value selects a metadata-schema in app/schemas/entry_metadata.py.

Available options:
knowledge,
skill,
process,
glossary,
memory,
bootstrap,
skill_index
​
version
integer
required
​
language
string
required
​
translation_group_id
string<uuid>
required
​
source
enum<string>
required

Where a knowledge entry originated from.

Available options:
manual,
import,
conversational,
learning_loop,
system
​
source_reference
string | null
required
​
embedding_model
string | null
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
summary
string | null
​
layer
string | null
Maximum string length: 50
​
tags
string[]
​
workspace_id
string<uuid> | null
​
created_by_user_id
string<uuid> | null
​
metadata
Metadata · object
​
search_keywords
string[]