Zum Inhalt springen

Ontheia API Reference

Diese Dokumentation beschreibt die verfügbaren API-Endpunkte des Ontheia-Hosts.

Alle Endpunkte (außer /auth/login, /auth/signup, /auth/logout und /health) erfordern ein gültiges Bearer-Token im Authorization-Header.

MethodePfadBeschreibung
POST/auth/signupRegistriert einen neuen Benutzer. Beachtet globale Einstellungen (allow_self_signup, require_admin_approval).
POST/auth/loginMeldet einen Benutzer an. Blockiert Accounts mit Status suspended oder pending.
POST/auth/logoutMeldet den aktuellen Benutzer ab (invalidiert Session).
GET/auth/meLiefert Profilinformationen des Benutzers inkl. role und status.
DELETE/auth/meArt. 17 DSGVO – Löscht den eigenen Account und alle persönlichen Daten unwiderruflich. Agenten, Tasks, Chains und Provider bleiben erhalten (Systemressourcen).
GET/auth/me/exportArt. 20 DSGVO – Exportiert alle persönlichen Daten als ontheia-export.json (Profil, Chats, Run-Logs, Memory-Einträge).
PUT/auth/profileAktualisiert das Benutzerprofil. Erlaubt die Steuerung des Admin-Memory-Zugriffs via allow_admin_memory.
POST/auth/change-passwordÄndert das Passwort des Benutzers.
GET/user/settingsRuft Benutzereinstellungen ab. Enthält u. a. runtime, uiFlags, promptOptimizer, builder, rollingSummary.
PUT/user/settingsSpeichert Benutzereinstellungen. Admins können globale Felder (z. B. rollingSummary) systemweit persistieren. Beispiel-Payload: { "rollingSummary": { "providerId": "openai", "modelId": "gpt-6-luna", "thresholdTokens": 32000, "minRecent": 20 } }.
GET/user/auditLiefert Audit-Logs für den Benutzer (Sitzungen, Runs).
  • active: Voller Zugriff auf das System.
  • pending: Account erstellt, wartet auf Admin-Freigabe. Login blockiert (account_pending).
  • suspended: Account durch Admin gesperrt. Login blockiert (account_suspended).

Agenten sind Konfigurationen für LLMs, Tasks sind spezifische Aufgabenprofile innerhalb eines Agenten.

MethodePfadBeschreibung
GET/agentsListet alle verfügbaren Agenten auf.
POST/agentsErstellt einen neuen Agenten.
GET/agents/:idLiefert Details zu einem spezifischen Agenten.
PATCH/agents/:idAktualisiert einen Agenten. Bleibt nach geänderten default_mcp_servers oder default_tools ein zugewiesener MCP-Server ohne gebundenes Tool (während andere Tools gebunden sind), enthält die Antwort warnings: [{ "code": "mcp_server_without_tools", "server": "<Name>" }] — der Agent kann die Tools dieses Servers nicht sehen.
DELETE/agents/:idLöscht einen Agenten.
POST/tasksErstellt einen neuen Task.
PATCH/tasks/:idAktualisiert einen Task.
DELETE/tasks/:idLöscht einen Task.
GET/tasks/:id/versionsListet die abgelösten Fassungen des Task-Kontexts, neueste zuerst. Nur Admin.
POST/tasks/:id/versions/:version/restoreSchreibt eine frühere Fassung in den Task zurück und liefert den aktualisierten Task. Nur Admin.
GET/agents/:agentId/memoryLiefert Memory-Einstellungen für einen Agenten.
PUT/agents/:agentId/memoryAktualisiert Memory-Einstellungen für einen Agenten.
GET/tasks/:taskId/memoryLiefert Memory-Einstellungen für einen Task.
PUT/tasks/:taskId/memoryAktualisiert Memory-Einstellungen für einen Task.

System- und Benutzer-Prompts zur Kontext-Erweiterung.

MethodePfadBeschreibung
GET/prompt-templatesListet Vorlagen auf (gefiltert nach Scope/Target).
POST/prompt-templatesErstellt eine neue Vorlage.
PUT/prompt-templates/:idAktualisiert eine bestehende Vorlage.
DELETE/prompt-templates/:idLöscht eine Vorlage.

Chains sind komplexe Workflows, die aus mehreren Schritten bestehen können.

MethodePfadBeschreibung
GET/chainsListet alle verfügbaren Chains auf.
POST/chainsErstellt eine neue Chain (Initialversion). Nur für Admins.
GET/chains/:idLiefert Details zu einer Chain.
PATCH/chains/:idAktualisiert Metadaten einer Chain. Nur für Admins.
DELETE/chains/:idLöscht eine gesamte Chain. Nur für Admins.
GET/chains/:id/versionsListet alle Versionen einer Chain auf. Nur für Admins.
POST/chains/:id/versionsErstellt eine neue Version für eine Chain. Nur für Admins.
POST/chains/:id/versions/activateSetzt eine spezifische Version als aktiv. Nur für Admins.
POST/chains/:id/runStartet die Ausführung einer Chain.

Geplante Agenten-Interaktionen basierend auf Zeitintervallen oder Einmalzeitpunkten.

MethodePfadBeschreibung
GET/api/cronListet alle konfigurierten Cron-Jobs des Benutzers auf.
POST/api/cronErstellt einen neuen Cron-Job.
PATCH/api/cron/:idAktualisiert die Konfiguration eines Cron-Jobs (z.B. Zeitplan, Status).
DELETE/api/cron/:idLöscht einen Cron-Job dauerhaft.
POST/api/cron/:id/runTriggert einen Cron-Job sofort manuell.
GET/api/cron/:id/runsLiefert den Ausführungsverlauf (letzte 20 Runs) für diesen spezifischen Job.

Felder POST/PATCH /api/cron:

FeldTypBeschreibung
namestringAnzeigename des Jobs.
schedulestring | nullCron-Ausdruck für wiederkehrende Jobs. Gegenseitig ausschließend mit run_at.
run_atISO 8601 | nullEinmaliger Ausführungszeitpunkt. Gegenseitig ausschließend mit schedule.
agent_iduuidZugeordneter Agent.
task_iduuid | nullOptionaler Task.
chain_iduuid | nullOptionale Chain.
prompt_template_iduuid | nullOptionale Prompt-Vorlage als Benutzernachricht.
prompt_textstring | nullDirekte Texteingabe als Benutzernachricht (Alternative zu prompt_template_id).
chat_idstring | nullBestehender Chat, in dem der Job fortgesetzt wird.
chat_title_templatestring | nullTitelvorlage mit {{name}} und {{timestamp}}.
notifybooleanErgebnis jedes Laufs in den Posteingang legen und, falls aktiviert, eine Desktop-Benachrichtigung senden. Fehler landen unabhängig davon im Posteingang.
approval_mode"granted" | "inbox"Tool-Freigabe. granted (Standard): Der Job genehmigt sich jeden Tool-Aufruf selbst. inbox: Tool-Aufrufe warten im Posteingang, außer bei Tools, die der Agent immer nutzen darf.
prevent_overlapbooleanÜberlappende Ausführungen verhindern.
activebooleanJob aktiv/inaktiv schalten.

Echtzeit-Benachrichtigungen (SSE):

MethodePfadBeschreibung
GET/api/eventsSSE-Stream für Echtzeit-Push-Events. Authentifizierung via Bearer-Token. Event-Typ: notification. type: "cron_complete" trägt job_id, job_name, chat_id, success; type: "inbox_item" trägt item_id, kind, bei neuen Einträgen title und chat_id, bei geschlossenen Freigaben closed: true.

Läufe, die ein anderes System auslöst. Konzept: Trigger (Webhook).

MethodePfadBeschreibung
POST/hooks/:idStartet den Lauf des Triggers. Keine Session; Token im Header Authorization: Bearer <Token> oder X-Ontheia-Token. Body: JSON bis 256 KB. Antwort 202 mit { status: "accepted", event_id, run_id } oder { status: "skipped", reason: "overlap" }. Fehler: 401 (Token falsch/fehlend, Trigger unbekannt oder inaktiv), 404 (Trigger global aus), 413, 415, 429.

Alle Routen erfordern eine Session und wirken nur auf die eigenen Trigger.

MethodePfadBeschreibung
GET/api/triggersListet die eigenen Trigger. Antwort: { triggers, enabled }; enabled ist der globale Schalter. Der Token-Hash wird nie ausgegeben.
POST/api/triggersLegt einen Trigger an. Antwort 201 mit { trigger, token } — die einzige Antwort, die das Token enthält.
PATCH/api/triggers/:idÄndert Felder eines Triggers.
DELETE/api/triggers/:idLöscht Trigger und Protokoll.
POST/api/triggers/:id/rotate-tokenErzeugt ein neues Token ({ token }); das bisherige ist sofort ungültig.
POST/api/triggers/:id/testStartet einen Lauf mit { payload } über die Session statt des Tokens. Zählt gegen dieselben Limits; funktioniert auch bei inaktivem Trigger.
GET/api/triggers/:id/eventsDie letzten 50 Protokolleinträge: id, received_at, status, source (webhook/test), run_id, chat_id, payload, error.

Trigger anderer Benutzer (nur Admin): Ein Admin legt mit user_id im Body von POST /api/triggers einen Trigger für einen anderen Benutzer an. Der Trigger gehört dann diesem Benutzer: Der Lauf arbeitet mit dessen Rechten, Ergebnisse und Freigaben landen in dessen Posteingang, und der Zugriff auf Agent, Task und Chain wird für ihn geprüft. GET /api/triggers?user_id=<uuid> listet dessen Trigger. Ändern, Löschen, Token erneuern, Testen und das Protokoll funktionieren für einen Admin bei jedem Trigger. Jeder Trigger enthält user_id. Ohne Admin-Rolle führt ein fremdes user_id zu 403, ein fremder Trigger zu 404.

Felder POST/PATCH /api/triggers:

FeldTypBeschreibung
namestringAnzeigename, höchstens 120 Zeichen. Pflicht beim Anlegen.
agent_iduuid | nullAgent. Agent oder Chain ist Pflicht.
task_iduuid | nullOptionaler Task.
chain_iduuid | nullOptionale Chain.
prompt_templatestringAnweisung mit {{payload}}, {{payload.a.b}}, {{name}}, {{timestamp}}. Leer = Standardtext mit allen Daten.
approval_mode"inbox" | "granted" | "denied"Tool-Freigabe. Standard inbox.
inbox_result"always" | "errors" | "never"Was der Lauf im Posteingang meldet. Standard always.
chat_idstring | nullBestehender Chat, in dem jeder Lauf fortgesetzt wird. Leer = neuer Chat pro Aufruf.
chat_title_templatestringTitelvorlage mit {{name}}, {{timestamp}} und {{payload.feld}} (einzeilig, höchstens 80 Zeichen je Feld).
rate_limit_per_mininteger1 – 600, Standard 10.
prevent_overlapbooleanAufrufe während eines laufenden Laufs überspringen.
activebooleanTrigger aktiv/inaktiv schalten.

Zielt ein Trigger auf einen Agenten, einen Task oder eine Chain, auf die der Besitzer keinen Zugriff hat, antwortet die Route mit 403 target_not_accessible.


Freigaben, Ergebnisse und Fehler von Hintergrundläufen. Konzept: Posteingang. Alle Routen erfordern eine Session und wirken nur auf die eigenen Einträge, auch für Admins.

MethodePfadBeschreibung
GET/api/inboxListet Einträge. Query: status (open Standard, all), limit (1 – 100, Standard 50), offset. Antwort: { items, total, open }. Offene Freigaben stehen vorn.
GET/api/inbox/count{ open, approvals } für den Zähler.
POST/api/inbox/:id/resolveBeantwortet eine Freigabe. Body: { mode: "once" | "always" | "deny" }. 409 approval_no_longer_pending, wenn der Lauf nicht mehr wartet.
POST/api/inbox/:id/doneSchließt ein Ergebnis oder einen Fehler. Für Freigaben 404.
POST/api/inbox/done-allSchließt alle offenen Ergebnisse und Fehler. Antwort: { ok, done }.

Eintrag: id, kind (approval/result/error), status (open/done/expired), run_id, chat_id (null, wenn der Chat nicht mehr existiert), trigger_type (cron/webhook), trigger_id, title, summary, payload, resolution, created_at, resolved_at. Bei Freigaben enthält payload die Felder call_id, server, tool, arguments und expires_at.

Eine Freigabe eines Hintergrundlaufs lässt sich weiterhin auch über POST /runs/:id/tool-approval beantworten.


Wiederverwendbare Fähigkeitsmodule, die Agenten mit spezialisierten Kenntnissen und Workflows erweitern. Skills werden als SKILL.md-Dateien unter sources/skills/ gespeichert und vom ScanService in die Datenbank indiziert.

MethodePfadBeschreibung
GET/api/skillsListet alle für den aktuellen Nutzer sichtbaren Skills (global + eigene user-scope Skills).
GET/api/skills/:idGibt einen einzelnen Skill inkl. vollständigem Body-Content zurück.
PATCH/api/skills/:idAktualisiert Skill-Metadaten — enabled, disable_model_invocation, user_invocable, model_override (nicht den Body — für Inhaltsänderungen die Datei direkt bearbeiten; active ist scanner-verwaltet und nicht patchbar).
DELETE/api/skills/:idDeaktiviert einen Skill dauerhaft (enabled = false) — löscht die Datei nicht und wird durch einen Rescan nicht rückgängig gemacht.
POST/api/skills/scanLöst einen manuellen Rescan von sources/skills/ aus. Nur Admin.
GET/api/agents/:id/skillsGibt alle dem Agenten zugewiesenen Skills zurück.
PUT/api/agents/:id/skillsSetzt die Skill-Zuweisung für einen Agenten (ersetzt bestehende). Body: { "skill_ids": ["uuid", ...] }. Nur Admin.

Skill-Objekt-Felder:

FeldTypBeschreibung
iduuidEindeutige ID. Stabil über Rescans hinweg.
namestringKebab-case Skill-Name (aus SKILL.md-Frontmatter).
descriptionstringWas der Skill tut und wann er verwendet werden soll (max. 1024 Zeichen).
when_to_usestring | nullZusätzliche Trigger-Hinweise (optionales Frontmatter-Feld).
contentstringVollständiger SKILL.md-Body (nur bei GET /api/skills/:id).
skill_dirstringAbsoluter Pfad zum Skill-Verzeichnis im Container. Dient als Pfad-Begrenzer für den MCP-Server.
scopeglobal | userglobal = für alle sichtbar; user = nur Owner.
owner_iduuid | nullNutzer-ID bei user-scope Skills; null bei globalen Skills.
activebooleanScanner-verwaltet: false wenn das Skill-Verzeichnis nicht mehr auf dem Dateisystem existiert. Wird bei jedem Rescan automatisch neu gesetzt.
enabledbooleanAdmin-verwaltet: persistenter Ein/Aus-Schalter, unabhängig von der Dateipräsenz. Übersteht Rescans. Ein Skill ist nur nutzbar wenn active = true AND enabled = true.

Interne MCP-Tools (zur Laufzeit für Agenten verfügbar):

ToolBeschreibung
activate_skill(name)Lädt vollständigen Skill-Body aus DB in den Kontext. Gibt Body + Ressourcen-Listing zurück.
read_skill_resource(skill_name, path)Liest eine Datei aus dem Skill-Verzeichnis (pfadbegrenzt).
write_skill_resource(skill_name, path, content)Schreibt eine Datei in das Skill-Verzeichnis (scope-Berechtigung wird geprüft).
create_skill(name, scope, content)Legt einen neuen Skill auf dem Dateisystem an und löst einen Rescan aus.

Runs repräsentieren die tatsächliche Ausführung eines Agenten oder einer Chain.

MethodePfadBeschreibung
POST/runsStartet einen neuen Agent-Run (Chat-Interaktion).
GET/runs/:idLiefert Details und Events eines Runs.
POST/runs/:id/stopBricht einen laufenden Run ab.
GET/runs/:id/streamSSE-Endpoint für Streaming-Events eines Runs.
POST/runs/:id/tool-approvalBestätigt oder lehnt eine Tool-Freigabe-Anfrage ab (erfordert call_id). Nur für eigene Runs; eine fremde Freigabe wird wie „nichts offen“ beantwortet (409 no_pending_toolcall).
GET/runs/recentListet die kürzlich ausgeführten Runs auf.

Interaktion mit dem Langzeitgedächtnis (pgvector).

MethodePfadBeschreibung
GET/memory/searchSemantische Suche. Query-Parameter: namespace (mehrfach), query, top_k (Seitengröße, max. 200), offset, min_score (Standard 0.3), include_hidden, project_id, lang, tags, metadata. Antwortet mit { namespaces, hits, offset, total, total_capped, has_more } — namespaces nennt, worin tatsächlich gesucht wurde. offset + top_k ist auf 1.000 begrenzt; bei einer Textsuche zählt total die Treffer unter den besten 1.000 Kandidaten (total_capped: true, wenn der Vorrat voll war), ohne Query alle passenden Einträge. Jeder Treffer trägt similarity (roher Kosinus, 0…1) und relevance (nach Namespace-Bonus und Rezenz, kann über 1 liegen); min_score prüft die relevance.
POST/memory/documentsLegt Einträge an (Array oder Einzelobjekt). Felder: namespace, content, metadata, ttl_seconds, class, observed_at.
PUT/memory/documents/:idBearbeitet einen Eintrag. Zusätzlich zu den Feldern oben: restore: true hebt Löschung und Ablösung auf. Erreicht auch Einträge, die aus der Suche gefallen sind.
DELETE/memory/documentsLöscht Einträge (Soft-Delete) anhand von namespace + content.
POST/memory/documents/:id/statusSetzt die Reife eines Eintrags: { "status": "confirmed" | "unconfirmed" }. Antwortet mit { ok, id, status, status_changed_at }. 409 wenn der Eintrag inzwischen abgelöst wurde, 404 wenn er gelöscht ist. superseded lässt sich hierüber nicht setzen.
POST/memory/documents/statusesAktueller Stand mehrerer Einträge: { "ids": [...] } → { statuses: { id: { status, statusChangedAt, superseded, deleted } } }. Ein Lesevorgang als POST, weil die Id-Liste nicht in eine URL gehört. Gelöschte und abgelöste Einträge werden mit Kennzeichnung zurückgegeben, nicht weggelassen — sonst wäre „gelöscht” von „unbekannt” nicht zu unterscheiden.
DELETE/memory/namespaceLeert einen ganzen Namespace.
GET/memory/namespacesListet alle für den Benutzer zugänglichen Namespaces auf.
GET/memory/healthStatus-Check des Memory-Systems (pgvector-Verbindung).
POST/memory/reembed⚠️ Experimentell – Fügt Einträge zur Re-Embedding-Warteschlange hinzu. Der Worker ist noch nicht vollständig implementiert.
GET/memory/auditAudit-Logs. Query-Parameter: limit, namespace (mit * als Präfixsuche), agent_id, task_id.
GET/memory/statsLiefert Statistiken zur Memory-Belegung nach Namespace.
POST/memory/ingest/directoryVerzeichnis-Import mit Fortschrittsmeldung (SSE).
POST/memory/convert/pdf2mdWandelt PDF-Dateien eines Verzeichnisses in Markdown um.
POST/memory/maintenance/cleanupDublettenbereinigung (hart löschend, mit vorherigem Backup).
POST/memory/maintenance/cleanup-expiredLöscht abgelaufene Einträge endgültig.

Organisation von Konversationen in Projekten.

MethodePfadBeschreibung
GET/projectsListet alle Projekte des Benutzers auf.
POST/projectsErstellt ein neues Projekt.
PATCH/projects/:idBenennt ein Projekt um oder ändert Metadaten.
DELETE/projects/:idLöscht ein Projekt inkl. zugehöriger Chats.
GET/chatsListet Chats auf (global oder gefiltert nach Projekt).
GET/chats/:chatIdLiefert Metadaten eines Chats.
PATCH/chats/:chatIdAktualisiert Chat-Einstellungen oder Projektzuordnung.
DELETE/chats/:chatIdLöscht einen Chat-Verlauf.
GET/chats/:chatId/messagesListet alle Nachrichten eines Chats auf.
PATCH/chats/:chatId/messages/:messageIdLöscht eine Nachricht (Soft-Delete) oder editiert sie.

Dateikarten und Panel-Editor. Jeder Dateizugriff läuft über die Skripte des files-Skills, damit dessen Wurzelverzeichnis-Prüfung und {user}-Isolation greifen. Alle Routen sind per RLS auf den eigenen Benutzer beschränkt.

MethodePfadBeschreibung
GET/api/artifacts/by-pathLöst einen Dateipfad zum zugehörigen Artefakt auf (Query path).
GET/api/artifacts/:idLiefert Metadaten und den gespeicherten Inhalt der aktuellen Version.
GET/api/artifacts/:id/rawStreamt die Bytes eines Binär-Artefakts (PDF) für die Leseansicht.
POST/api/artifacts/:id/refreshLiest die Datei neu ein und legt bei Änderung eine neue Version an.
POST/api/artifacts/:id/saveSchreibt bearbeiteten Inhalt zurück; bei Prüfsummen-Konflikt 409.
POST/api/artifacts/materializeLegt einen Chat-Entwurf als neue Datei an; existiert sie bereits, 409.

Verwaltung von Model Context Protocol Servern und Tool-Konfigurationen.

MethodePfadBeschreibung
GET/servers/configsListet MCP-Server-Konfigurationen auf. Jeder Eintrag enthält status_summary (state: running, running_no_tools, failed, stopped, starting, never_started; dazu since, tool_count, error), status_message (derselbe Zustand als englischer Satz) und recent_events (bis zu 20 Ereignisse, neueste zuerst: at, kind = start_ok | start_failed | stop | crash, message, tool_count).
POST/servers/configsSpeichert/Aktualisiert eine MCP-Server-Konfiguration.
DELETE/servers/configs/:nameLöscht eine MCP-Server-Konfiguration.
POST/servers/validatePrüft eine Konfiguration auf Korrektheit. Nur Admin.
POST/servers/startStartet einen MCP-Server manuell. Nur Admin.
POST/servers/stop/:nameStoppt einen spezifischen MCP-Server-Prozess. Nur Admin.
POST/servers/stop-allStoppt alle laufenden MCP-Server. Nur Admin.
GET/servers/processesListet aktuell laufende MCP-Prozesse auf.
GET/mcp/toolsListet alle verfügbaren Tools aller aktiven Server auf.
GET/providersListet alle registrierten LLM-Provider auf.
POST/providersErstellt oder aktualisiert einen LLM-Provider.
PUT/providers/:idAktualisiert einen spezifischen LLM-Provider.
DELETE/providers/:idLöscht einen spezifischen LLM-Provider.
POST/providers/testTestet die Verbindung zu einem LLM-Provider.

Funktionen exklusiv für Benutzer mit der Rolle admin.

Administratoren können Benutzerkonten verwalten, jedoch aus Datenschutzgründen (DSGVO) den Memory-Zugriff nicht für sich selbst freischalten. Dies muss durch den jeweiligen Benutzer in seinen eigenen Profileinstellungen geschehen.

MethodePfadBeschreibung
GET/admin/usersListet alle Benutzer des Systems auf (alphabetisch sortiert).
POST/admin/usersErstellt einen neuen Benutzer (Password, Role, Status).
PATCH/admin/users/:idAktualisiert einen Benutzer (Name, Role, Status).
DELETE/admin/users/:idLöscht einen Benutzer endgültig.

Globale Konfiguration des Ontheia-Hosts.

MethodePfadBeschreibung
GET/admin/settingsRuft alle globalen Systemeinstellungen ab.
PATCH/admin/settingsAktualisiert spezifische Systemeinstellungen (z.B. allow_self_signup, max_tool_calls, triggers_enabled, inbox_approval_timeout_hours).
GET/admin/model-usageListet alle verwendeten Provider/Modell-Paare mit den Agenten, aktiven Chains und Systemeinstellungen (promptOptimizer, rollingSummary), die sie nutzen; known zeigt, ob das Paar als Chat-Modell angelegt ist. Agent-Builder ausgenommen.
POST/admin/model-replaceErsetzt ein Modell an den gewählten Stellen. Body: { from: { provider, model }, to: { provider, model }, agent_ids, chain_ids, settings }. to muss ein aktives Chat-Modell sein. Chains erhalten eine neue aktive Version. Gibt die geänderten agents, chains und settings zurück.
GET/admin/system/statusGibt Systemstatus zurück: Memory-Modus (disabled/cloud/local) und installierte Version. Nützlich für Monitoring und Skripte.
MethodePfadBeschreibung
GET/admin/namespace-rulesListet Regeln für Vektor-Namespaces auf.
POST/admin/namespace-rulesErstellt eine neue Namespace-Regel.
PUT/admin/namespace-rules/:idAktualisiert eine Namespace-Regel.
DELETE/admin/namespace-rules/:idLöscht eine Namespace-Regel.
GET/vector/healthStatus-Check der pgvector-Anbindung inkl. Index-Statistiken.
POST/vector/maintenanceTriggert Wartungsaufgaben (vacuum, reindex).
POST/admin/memory/bulk-ingestMassenimport von .md-Dateien aus einem Container-Verzeichnis in einen Vektor-Namespace. Body: { namespace, path?, recursive? }. Nur vector.global.*-Namespaces erlaubt. Gibt { ok, inserted, files, chunks } zurück.

Ontheia verfolgt einen strikten Datenschutz-Ansatz für das Langzeitgedächtnis (Memory).

Jeder Benutzer kann seine eigenen Daten eigenständig verwalten — ohne Administratoreingriff.

GET /auth/me/export — Recht auf Datenportabilität (Art. 20 DSGVO)

Abschnitt betitelt „GET /auth/me/export — Recht auf Datenportabilität (Art. 20 DSGVO)“

Exportiert alle personenbezogenen Daten des eingeloggten Benutzers als strukturiertes JSON.

Enthält:

  • Benutzerprofil (Name, E-Mail, Rolle, Erstellungsdatum)
  • Benutzereinstellungen (Theme, Sprache, UI-Flags)
  • Chats und Chatnachrichten
  • Run-Logs (Ausführungshistorie)
  • Cron-Jobs (Automatisierungszeitpläne)
  • Memory-Einträge aus beiden Vektortabellen (vector.documents, vector.documents_768)

Nicht enthalten (Systemressourcen, mehreren Nutzern zugeordnet):

  • Agenten, Tasks, Chains, Chain-Versionen
  • Provider, MCP-Server-Konfigurationen

Response: application/json als Dateidownload (Content-Disposition: attachment; filename="ontheia-export.json")

{
"exportedAt": "iso-timestamp",
"user": { "id": "uuid", "email": "string", "name": "string", "role": "string", "created_at": "timestamp" },
"chats": [
{
"id": "string", "title": "string", "created_at": "timestamp",
"messages": [{ "role": "user|agent|system|tool", "content": "string", "createdAt": "timestamp" }]
}
],
"runs": [{ "id": "uuid", "run_id": "uuid", "agent_id": "string", "chain_id": "uuid|null", "created_at": "timestamp" }],
"memoryEntries": [{ "namespace": "string", "content": "string", "createdAt": "timestamp" }]
}

DELETE /auth/me — Recht auf Löschung (Art. 17 DSGVO)

Abschnitt betitelt „DELETE /auth/me — Recht auf Löschung (Art. 17 DSGVO)“

Löscht den Account und alle personenbezogenen Daten des eingeloggten Benutzers unwiderruflich.

Gelöscht wird:

  • Benutzerprofil (app.users)
  • Alle Sessions (app.sessions)
  • Benutzereinstellungen (app.user_settings)
  • Chats und Chatnachrichten (app.chats, app.chat_messages)
  • Run-Logs (app.run_logs) mit user_id des Benutzers
  • Cron-Jobs (app.cron_jobs) des Benutzers
  • Alle Vektor-Einträge in vector.documents und vector.documents_768, deren Namespace die User-ID als Pfadsegment enthält (z.B. vector.user.<id>.*, vector.agent.<agent-id>.<id>.*)

Nicht gelöscht (Systemressourcen):

  • Agenten, Tasks, Chains, Provider, MCP-Server-Konfigurationen, Embeddings

Response: 204 No Content

⚠️ Diese Operation kann nicht rückgängig gemacht werden. Die aktuelle Session wird ebenfalls invalidiert.


Um den Memory eines Benutzers einzusehen oder zu verwalten (z.B. für Support-Zwecke), benötigt ein Administrator die explizite Erlaubnis des Benutzers.

  1. Benutzer-Steuerung: Der Benutzer aktiviert in seinem Profil (/auth/profile) die Option allow_admin_memory.
  2. Auditierung: Jeder Zugriff durch einen Administrator auf den Memory eines Benutzers wird im System-Audit-Log protokolliert.
  3. Technische Sperre: Ohne diese Erlaubnis blockiert das Row-Level-Security (RLS) System der Datenbank jeglichen Zugriff, selbst wenn der Administrator administrative Rechte besitzt.
  4. Keine Selbst-Zuweisung: Administratoren können das Feld allow_admin_memory über die API /admin/users nicht ändern.

Die Memory-Policy eines Agenten (allowed_write_namespaces, write_namespace) unterstützt Template-Variablen, die zur Laufzeit mit der Session-User-ID befüllt werden:

VariableBedeutung
${user_id}UUID des eingeloggten Benutzers
${agent_id}UUID des ausführenden Agenten
${chat_id}UUID des aktiven Chats
${session_id}UUID des aktuellen Runs

Empfehlung: Namespaces für persönliche Daten immer mit ${user_id} konfigurieren — niemals eine UUID hardcoden. Andernfalls schreiben alle Benutzer dieses Agenten in denselben Namespace.

✅ vector.user.${user_id}.memory
✅ vector.agent.${agent_id}.session.${chat_id}
✅ vector.global.knowledge
❌ vector.user.b6a38fa5-ed09-4bde-8634-eb7e80275989.memory ← hardcodierte UUID
❌ vector.user.*.memory ← Wildcard an user_id-Position

Das memory-write-Tool zeigt dem LLM zur Laufzeit die konkrete User-ID des eingeloggten Benutzers in der Tool-Beschreibung — eine versehentliche Nutzung fremder Namespaces wird damit verhindert. Die serverseitige Namespace-Validierung (allowed_write_namespaces) ist die letzte Verteidigungslinie.


Allgemeine Systeminformationen und Health-Checks.

MethodePfadBeschreibung
GET/healthStatus-Check. Liefert { status: 'ok', rootless: boolean | null }. Das Feld rootless gibt das Ergebnis des Docker-Rootless-Checks beim Serverstart an (true=rootless, false=nicht rootless, null=nicht prüfbar).
GET/metricsLiefert Prometheus-Metriken.

{
"id": "uuid",
"email": "string",
"name": "string | null",
"role": "admin | user",
"status": "active | pending | suspended",
"lastLoginAt": "iso-timestamp | null",
"createdAt": "iso-timestamp",
"allowAdminMemory": "boolean (read-only for administrators)"
}

Repräsentiert eine einzelne Nachricht in einem Chat.

{
"id": "uuid",
"role": "user | agent | system | tool",
"content": "string",
"createdAt": "iso-timestamp",
"metadata": {
"usage": {
"prompt": "integer",
"completion": "integer"
},
"status": "running | success | error",
"streaming": "boolean"
}
}

Verwendet im Endpunkt POST /runs.

{
"agent_id": "uuid (optional)",
"task_id": "uuid (optional)",
"chain_id": "uuid (optional)",
"chain_version_id": "uuid (optional)",
"provider_id": "string (required, pattern: ^[a-z0-9][a-z0-9_-]{0,63}$)",
"model_id": "string (required, max: 200)",
"messages": [
{
"id": "string (optional)",
"role": "system | user | assistant | tool",
"content": "string | [{ type: 'text', text: 'string' }]",
"name": "string (optional)",
"tool_call_id": "string (optional)"
}
],
"tool_approval": "prompt | granted | denied (optional, Standard: prompt)",
"tool_permissions": { "<server>::<tool>": "once | always" },
"options": {
"temperature": "number (0-2)",
"max_tokens": "integer (1-32768)",
"metadata": "object"
}
}

tool_approval legt fest, wie Tool-Aufrufe behandelt werden: Mit prompt (Standard) wartet der Lauf auf die Freigabe über POST /runs/:id/tool-approval, mit granted führt er sie ohne Rückfrage aus, mit denied lehnt er sie ab. tool_permissions gibt einzelne Tools vorab frei (Schlüssel server::tool). Beide Felder können auch in options.metadata übergeben werden (so macht es die WebUI); ein Feld auf oberster Ebene hat Vorrang. Andere Werte werden ignoriert.

Verwendet im Endpunkt POST /runs/:id/tool-approval.

{
"tool_key": "string (required, z.B. 'server::tool')",
"call_id": "string (required, eindeutige ID des Tool-Calls)",
"mode": "once | always | deny (required)"
}

Verwendet in den Endpunkten POST /agents und PATCH /agents/:id (beide admin-only; bei PATCH sind alle Felder optional).

{
"label": "string (required)",
"description": "string",
"provider_id": "string",
"model_id": "string",
"tool_approval_mode": "prompt | granted | denied",
"default_mcp_servers": ["string"],
"default_tools": [ { "server": "string", "tool": "string" } ],
"default_tool_permissions": { "<server>::<tool>": "once | always" },
"metadata": {},
"max_tool_calls": "Ganzzahl 1–1000 oder null (optional — eigene Aufrufgrenze pro Lauf; null = globale Einstellung. Wird in metadata gespeichert, ohne die übrigen Metadaten zu ersetzen.)",
"visibility": "private | public",
"owner_id": "uuid (optional — Besitzer; Standard: anlegender Admin. Bei PATCH: Ownership-Übertragung.)",
"allowed_user_ids": ["uuid oder E-Mail (Berechtigte Benutzer)"],
"active": "boolean",
"show_in_composer": "boolean",
"tasks": [ "TaskCreate Object" ]
}

Verwendet im Endpunkt POST /tasks oder eingebettet in AgentCreate.

{
"name": "string (required)",
"description": "string",
"prompt": "string",
"tools": [
{
"server": "string",
"tool": "string"
}
],
"chains": [
{
"role": "pre | main | post",
"chain_version_id": "uuid",
"overrides": {}
}
]
}

Definiert den Workflow einer Chain. Verwendet in POST /chains/:id/versions.

Steps (Array von Step-Objekten): Ein Step muss id und type haben. Verfügbare Typen: llm, tool, router, branch, parallel, delay, loop, rest_call, memory_search, memory_write.

Beispiel Step (LLM):

{
"id": "step1",
"type": "llm",
"prompt": "Hello ${input.text}",
"model": "gpt-6.1-terra",
"provider": "openai"
}

Edges (Verbindungen):

[
{
"from": "step1",
"to": "step2",
"map": {
"output": "input"
}
}
]