Skip to main content
POST
/
api
/
knowledge-entries
curl -X POST https://acme.big-panda.ai/api/knowledge-entries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reklamations-Workflow",
    "content": "Bei Reklamationen folgendermaßen vorgehen ...",
    "category_id": "cat_workflows",
    "type": "process",
    "visibility": "internal",
    "tags": ["support", "reklamation"]
  }'

{
  "id": "entry_a8b3c1d2",
  "title": "Reklamations-Workflow",
  "type": "process",
  "visibility": "internal",
  "version": 1,
  "category_id": "cat_workflows",
  "tags": ["support", "reklamation"],
  "created_at": "2026-04-29T22:15:00Z",
  "updated_at": "2026-04-29T22:15:00Z"
}
Diese Seite ist eine Demo-Vorlage für das API-Doku-Pattern. Die produktive Referenz wird in Phase 2 automatisch aus den OpenAPI-Specs der Services generiert (siehe ROADMAP A.2 Phase 2).

​
Endpoint

POST https://<dein-tenant>.big-panda.ai/api/knowledge-entries
Big Panda routet pro Tenant über eigene Subdomain. <dein-tenant> ersetzt du durch deine Tenant-ID (z.B. acme.big-panda.ai).

​
Authentifizierung

OAuth-2.1-Bearer-Token im Authorization-Header. Token-Anforderung: Scope knowledge:write. OAuth-Setup siehe Tutorial: Eigene App per OAuth.

​
Request

​
Headers

​
Authorization
string
required
Bearer-Token: Bearer <dein-access-token>
​
Content-Type
string
required
application/json

​
Body

​
title
string
required
Titel des Eintrags. Wird im Admin-UI, in Such-Ergebnissen und im Widget angezeigt.
​
content
string
required
Volltext-Inhalt des Eintrags. Markdown wird gerendert (Headings, Listen, Code-Blocks, Links).
​
category_id
string
required
ID der Kategorie, in die der Eintrag eingeordnet wird. Muss für den authentifizierten User sichtbar sein.
​
type
string
default:"knowledge"
Document-Type. Einer von: knowledge, skill, memory, process, glossary. Siehe Document-Types.
​
visibility
string
default:"internal"
Sichtbarkeits-Stufe. Einer von: public, internal, restricted, community, personal. Siehe Drei-Achsen-Auth.
​
tags
string[]
Liste freier Tags zur Kategorisierung. Wird im Widget als Filter nutzbar.
​
metadata
object
Type-spezifische Metadaten. Schema hängt von type ab — bei process z.B. steps[], bei skill z.B. trigger_description. Siehe Document-Types.

​
Response

​
201 Created

​
id
string
UUID des erstellten Eintrags. Format: entry_xxxxxxxx.
​
title
string
Titel wie übergeben.
​
type
string
Document-Type wie übergeben (oder knowledge als Default).
​
visibility
string
Sichtbarkeits-Stufe wie übergeben (oder internal als Default).
​
version
integer
Versions-Counter. Bei Anlage immer 1. Wird mit jedem Edit hochgezählt (siehe Versionierung).
​
created_at
string
Zeitstempel der Anlage in UTC.
​
updated_at
string
Zeitstempel der letzten Änderung. Bei Anlage gleich created_at.
curl -X POST https://acme.big-panda.ai/api/knowledge-entries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reklamations-Workflow",
    "content": "Bei Reklamationen folgendermaßen vorgehen ...",
    "category_id": "cat_workflows",
    "type": "process",
    "visibility": "internal",
    "tags": ["support", "reklamation"]
  }'

{
  "id": "entry_a8b3c1d2",
  "title": "Reklamations-Workflow",
  "type": "process",
  "visibility": "internal",
  "version": 1,
  "category_id": "cat_workflows",
  "tags": ["support", "reklamation"],
  "created_at": "2026-04-29T22:15:00Z",
  "updated_at": "2026-04-29T22:15:00Z"
}

​
Fehler

​
400 Bad Request
Validierungs-Fehler. Häufig: metadata passt nicht zum gewählten type. Response-Body enthält detail mit Pydantic-Fehler-Liste.
​
401 Unauthorized
Token fehlt, ist abgelaufen oder ungültig. Erneuere via Refresh-Token oder neu autorisieren.
​
403 Forbidden
Token hat nicht den Scope knowledge:write, oder die User-Rolle erlaubt das Schreiben dieses type nicht (z.B. skill-Schreiben ist auf Admin/Supervisor beschränkt — siehe Schreibrechts-Enforcement).
​
404 Not Found
Die category_id existiert nicht oder ist für den authentifizierten User nicht sichtbar.
Beim Anlegen eines skill-Eintrags wird automatisch der skill_index-Singleton aktualisiert (atomar in derselben Transaktion). Konflikte sind durch Optimistic-Locking abgesichert — bei parallelen Schreib-Vorgängen kann eine Anfrage mit 409 Conflict zurückkommen.