API-Referenz

Übersicht

Das OpenCognit Backend stellt eine vollständige REST API auf Port 3201 bereit. Alle Antworten werden im JSON-Format zurückgegeben.

Basis-URL: http://localhost:3201

Authentifizierung

OpenCognit verwendet JWT (JSON Web Token) für alle geschützten Endpoints. Der Token wird im Authorization-Header als Bearer-Token übergeben.

Authorization: Bearer <dein-jwt-token>

Token erhalten

POST /api/auth/registrieren
Content-Type: application/json

{
  "name": "Max Müller",
  "email": "max@beispiel.de",
  "passwort": "sicheres-passwort-123"
}

Antwort:

{ "token": "eyJhbGci...", "benutzer": { "id": "...", "name": "Max Müller", "rolle": "admin" } }

POST /api/auth/anmelden
Content-Type: application/json

{
  "email": "max@beispiel.de",
  "passwort": "sicheres-passwort-123"
}

Antwort:

{ "token": "eyJhbGci...", "benutzer": { "id": "...", "name": "Max Müller" } }

GET /api/auth/ich
Authorization: Bearer <token>

Antwort:

{ "id": "...", "name": "Max Müller", "email": "max@beispiel.de", "rolle": "admin" }

Unternehmen

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen`	Alle Unternehmen des Benutzers
`POST`	`/api/unternehmen`	Neues Unternehmen erstellen
`GET`	`/api/unternehmen/:id`	Unternehmen-Details
`PATCH`	`/api/unternehmen/:id`	Unternehmen aktualisieren
`GET`	`/api/unternehmen/:id/dashboard`	Dashboard-Daten
`GET`	`/api/unternehmen/:id/aktivitaet`	Aktivitätsfeed
`GET`	`/api/unternehmen/:id/kosten/zusammenfassung`	Kostenübersicht

Unternehmen erstellen

POST /api/unternehmen
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Mein KI-Unternehmen",
  "beschreibung": "Ein autonomes Team für Software-Entwicklung.",
  "ziel": "Baue eine SaaS-Plattform für kleine Unternehmen."
}

Antwort:

{
  "id": "unt-abc123",
  "name": "Mein KI-Unternehmen",
  "status": "active",
  "erstelltAm": "2026-04-04T10:00:00Z"
}

Experten (Agenten)

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen/:id/experten`	Alle Agenten eines Unternehmens
`POST`	`/api/unternehmen/:id/experten`	Neuen Agenten anlegen
`GET`	`/api/experten/:id`	Agent-Details (Status, Skills, Config)
`PATCH`	`/api/experten/:id`	Agent aktualisieren
`DELETE`	`/api/experten/:id`	Agent löschen
`POST`	`/api/experten/:id/pausieren`	Heartbeat pausieren
`POST`	`/api/experten/:id/fortsetzen`	Heartbeat reaktivieren
`GET`	`/api/experten/:id/aktivitaet`	Aktivitätslog des Agenten
`GET`	`/api/experten/:id/inbox`	Offene Aufgaben (Heartbeat-Inbox)
`POST`	`/api/experten/:id/skills`	Skill hinzufügen
`DELETE`	`/api/experten/:id/skills/:skillId`	Skill entfernen

Agenten anlegen

POST /api/unternehmen/:id/experten
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Anna Schmidt",
  "rolle": "Backend Developer",
  "titel": "Senior Engineer",
  "verbindungsTyp": "claude",
  "verbindungsConfig": {
    "model": "claude-sonnet-4-6",
    "maxTokens": 8096
  },
  "faehigkeiten": ["nodejs", "postgresql", "rest-api"],
  "zyklusAktiv": true,
  "zyklusIntervallSek": 300,
  "budgetMonatCent": 10000
}

Aufgaben (Tasks)

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen/:id/aufgaben`	Alle Aufgaben
`POST`	`/api/unternehmen/:id/aufgaben`	Neue Aufgabe erstellen
`GET`	`/api/aufgaben/:id`	Aufgaben-Details
`PATCH`	`/api/aufgaben/:id`	Aufgabe aktualisieren
`POST`	`/api/aufgaben/:id/checkout`	Execution Lock setzen
`POST`	`/api/aufgaben/:id/release`	Execution Lock freigeben
`GET`	`/api/aufgaben/:id/kommentare`	Kommentare abrufen
`POST`	`/api/aufgaben/:id/kommentare`	Kommentar hinzufügen

Aufgabe erstellen

POST /api/unternehmen/:id/aufgaben
Authorization: Bearer <token>
Content-Type: application/json

{
  "titel": "Benutzer-Authentifizierung implementieren",
  "beschreibung": "JWT-basierte Auth mit Refresh-Tokens. E-Mail-Verifikation optional.",
  "prioritaet": "hoch",
  "zugewiesenAn": "<experten-id>",
  "parentId": null,
  "blockedBy": null
}

Routinen

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen/:id/routinen`	Alle Routinen
`POST`	`/api/unternehmen/:id/routinen`	Routine erstellen
`GET`	`/api/routinen/:id`	Routine-Details
`PATCH`	`/api/routinen/:id`	Routine aktualisieren
`DELETE`	`/api/routinen/:id`	Routine löschen
`GET`	`/api/routinen/:id/triggers`	Trigger abrufen
`POST`	`/api/routinen/:id/triggers`	Trigger anlegen
`POST`	`/api/routinen/:id/trigger`	Manuell auslösen
`GET`	`/api/routinen/:id/ausfuehrungen`	Ausführungshistorie

Genehmigungen

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen/:id/genehmigungen`	Offene Genehmigungen
`POST`	`/api/genehmigungen/:id/genehmigen`	Genehmigen
`POST`	`/api/genehmigungen/:id/ablehnen`	Ablehnen

Einstellungen

Method	Endpoint	Beschreibung
`GET`	`/api/einstellungen`	Alle Einstellungen abrufen
`PUT`	`/api/einstellungen/:key`	Einstellung setzen

PUT /api/einstellungen/anthropic_api_key
Authorization: Bearer <token>
Content-Type: application/json

{ "wert": "sk-ant-api03-..." }

System & Health

Method	Endpoint	Beschreibung
`GET`	`/api/health`	Health-Check (UP/DOWN)
`GET`	`/api/system/status`	Systemlast, aktive Heartbeats, Budget-Status

GET /api/health
# Antwort: { "status": "UP", "timestamp": "2026-04-04T10:00:00Z" }

GET /api/system/status
# Antwort: { "aktiveAgenten": 3, "offeneAufgaben": 12, "heartbeatsHeute": 47 }

Chat

Direktes Board ↔ Agent-Messaging pro Unternehmen:

Method	Endpoint	Beschreibung
`GET`	`/api/unternehmen/:id/chat`	Chat-Verlauf abrufen
`POST`	`/api/unternehmen/:id/chat`	Nachricht senden

POST /api/unternehmen/:id/chat
Authorization: Bearer <token>
Content-Type: application/json

{ "nachricht": "Wie ist der Status der Login-Seite?", "empfaengerId": "<agenten-id>" }

WebSocket — Real-Time Updates

OpenCognit sendet Live-Updates über WebSocket an alle verbundenen Clients.

Verbindung:

const ws = new WebSocket('ws://localhost:3201/ws');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data);
};

Event-Typen:

Event `type`	Beschreibung
`agent_status`	Agent-Status geändert (`idle` / `running` / `paused` / `error`)
`task_started`	Agent hat eine Aufgabe übernommen und Execution Lock gesetzt
`task_completed`	Aufgabe nach erfolgreicher Ausführung auf `done` gesetzt
`task_escalated`	Aufgabe nach 3 aufeinanderfolgenden Fehlern an CEO eskaliert
`tasks_unblocked`	Blockierte Aufgaben wurden nach Abhängigkeitsauflösung freigegeben
`approval_needed`	Neue Genehmigungsanfrage wartet auf Board-Entscheidung
`goal_achieved`	Unternehmensziel vom CEO als erreicht markiert
`budget_warning`	Agent nähert sich oder überschreitet das Monatsbudget
`expert_deleted`	Ein Agent wurde gelöscht
`meeting_created`	Agenten haben ein Koordinationsgespräch geplant
`meeting_updated`	Meeting-Ergebnis oder -Status geändert
`agents_imported`	Massen-Import von Agenten abgeschlossen
`routine_executed`	Eine geplante Routine wurde ausgeführt
`aktivitaet`	Neuer Aktivitätslog-Eintrag
`kosten_update`	Token-Kosten-Tracking aktualisiert

Das Frontend nutzt WebSocket für das Echtzeit-Dashboard. Alle Änderungen (Agent-Status, Task-Updates, neue Kommentare) werden sofort ohne Page-Refresh angezeigt.

Fehler-Antworten

Alle Endpoints geben strukturierte Fehler zurück:

{
  "fehler": "Aufgabe nicht gefunden",
  "code": "NOT_FOUND",
  "status": 404
}

HTTP-Status	Bedeutung
`200`	Erfolg
`201`	Ressource erstellt
`400`	Ungültige Anfrage
`401`	Nicht authentifiziert
`403`	Keine Berechtigung
`404`	Ressource nicht gefunden
`409`	Konflikt (z.B. Execution Lock aktiv)
`500`	Server-Fehler

On this page