HydraHive API-Referenz

Auth

POST/auth/login

Authentifizierung mit Benutzername und Passwort. Gibt einen JWT-Token zurück.

Request Body:

{ "username": "admin", "password": "geheim" }

Response 200:

{ "access_token": "eyJ...", "token_type": "bearer" }

GET/auth/me

Gibt Informationen über den aktuell eingeloggten Benutzer zurück.

Response 200:

{ "username": "admin" }

Setup

GET/setup/status

Prüft ob der Setup-Wizard noch benötigt wird (kein Benutzer angelegt).

Response 200:

{ "needs_setup": true }

POST/setup

Legt den ersten Admin-Account an. Nur verfügbar solange noch kein Benutzer existiert.

Response 201:

{ "created": true, "username": "admin", "role": "admin" }

System

GET/health

Health-Check ohne Authentifizierung. Für Monitoring und Load-Balancer geeignet.

Response 200:

{ "status": "ok" }

GET/status

Detaillierter Systemstatus mit Discovery-, Projekt-, Session- und Laufzeit-Informationen.

Response 200:

{
  "discovery": { ... },
  "projects": { ... },
  "sessions": { ... },
  "runtime": { ... }
}

GET/admin/runtime/status

Runtime-Fingerprint für Audits und Support mit Deploy-Metadaten, Laufzeitstatus und verdichteter Core-Log-Zusammenfassung.

Response 200:

{
  "service": { "name": "hydrahive-core", "version": "0.1.0" },
  "deployment": { ... },
  "runtime": { ... },
  "audit": {
    "core_journal": {
      "available": true,
      "count": 200,
      "error_count": 2,
      "warn_count": 4,
      "first_timestamp": "2026-03-20 10:00:01",
      "last_timestamp": "2026-03-20 11:01:30",
      "top_signatures": [
        { "signature": "restart loop detected", "count": 3 }
      ]
    }
  }
}

Agenten

GET/agents

Gibt eine Liste aller registrierten Agenten zurück.

GET/agents/{id}

Gibt Details zu einem einzelnen Agenten zurück.

POST/agents

Erstellt einen neuen Agenten.

PUT/agents/{id}

Aktualisiert einen bestehenden Agenten. Body-Felder wie bei POST.

DELETE/agents/{id}

Löscht einen Agenten. Response 204 No Content.

GET/agents/{id}/soul

Gibt den Soul-Text (Persönlichkeitsbeschreibung) des Agenten als Plaintext zurück.

GET/agents/{id}/logs

Gibt die letzten Log-Einträge des Agenten zurück.

Agent Skills

GET/agents/{id}/skills

Gibt alle Skills eines Agenten zurück.

POST/agents/{id}/skills

Erstellt einen neuen Skill für den Agenten.

PUT/agents/{id}/skills/{filename}

Aktualisiert einen bestehenden Skill. Body-Felder wie bei POST.

DELETE/agents/{id}/skills/{filename}

Löscht einen Skill. Response 204 No Content.

Projekte

GET/projects

Gibt eine Liste aller Projekte zurück.

GET/projects/{id}

Gibt Details zu einem einzelnen Projekt zurück.

POST/projects

Erstellt ein neues Projekt.

POST/projects/{id}/provision

Provisioniert ein Projekt: legt Linux-User, Verzeichnis, Matrix-Room und optionale Samba-Freigabe an.

DELETE/projects/{id}/provision

Entfernt die Provisionierung eines Projekts (Linux-User, Freigaben). Das Projekt selbst bleibt bestehen.

DELETE/projects/{id}

Löscht ein Projekt vollständig. Response 204 No Content.

Chat

POST/projects/{id}/message

Sendet eine Nachricht an den Boss-Agenten eines Projekts. Wartet auf die vollständige Antwort.

Request Body:

{ "content": "Erstelle einen Bericht über Q1." }

Response 200:

{
  "response": "Hier ist der Q1-Bericht...",
  "workers": ["steuer-agent", "buchhalter"],
  "session_id": "sess_abc123"
}

POST/projects/{id}/message/stream

Sendet eine Nachricht und empfängt die Antwort als Server-Sent Events (SSE). Jedes Event enthält einen JSON-Payload.

data: {"text": "Hier "}
data: {"text": "ist "}
data: {"text": "der Bericht..."}
data: {"done": true}

# Bei Fehler:
data: {"error": "LLM nicht erreichbar"}

GET/projects/{id}/session/history

Gibt die Chat-History der aktuellen Session zurück.

Integrationen

GET/me/platforms

Einheitlichen Status der persönlichen Plattform-Integrationen abrufen.

{
  "username": "till",
  "platforms": [
    {
      "platform": "matrix",
      "label": "Matrix",
      "supported": true,
      "configured": true,
      "connected": true,
      "details": { "matrix_id": "@till:matrix.local" }
    },
    {
      "platform": "discord",
      "label": "Discord",
      "supported": true,
      "configured": true,
      "connected": true,
      "details": { "guild_id": "123", "channel_ids": ["111", "222"] }
    },
    {
      "platform": "telegram",
      "label": "Telegram",
      "supported": false,
      "configured": false,
      "connected": false,
      "details": { "status": "planned" }
    }
  ]
}

Webhooks

GET/projects/{id}/webhooks

Gibt alle konfigurierten Webhooks eines Projekts zurück.

POST/projects/{id}/webhooks

Erstellt einen neuen ausgehenden Webhook für ein Projekt.

Verfügbare Events: message, agent_error, provision, agent_start, agent_stop

DELETE/projects/{id}/webhooks/{webhook_id}

Löscht einen Webhook. Response 204 No Content.

POST/projects/{id}/webhooks/test

Sendet einen Test-Request an alle konfigurierten Webhooks des Projekts.

POST/hooks/{id}/wake

Kein Auth erforderlich. Externer Trigger-Endpoint für eingehende Webhooks. Startet den Boss-Agenten des Projekts asynchron.

Request Body:

{ "message": "Neuer Git-Push auf main — bitte Code-Review starten" }

Response 202:

{ "accepted": true, "project_id": "mein-projekt" }

Benutzer

GET/users

Gibt eine Liste aller Benutzer zurück.

POST/users

Erstellt einen neuen Benutzer.

DELETE/users/{username}

Löscht einen Benutzer. Der eigene Account kann nicht gelöscht werden. Response 204 No Content.

PUT/users/{username}/password

Ändert das Passwort eines Benutzers.

{ "password": "neues-passwort" }

Audit-Log

GET/audit/logs

Gibt Audit-Log-Einträge zurück, optional gefiltert.

Response 200:

{
  "logs": [
    {
      "id": "log_abc",
      "timestamp": "2026-03-20T14:32:00Z",
      "user": "admin",
      "action": "user.login",
      "target": "admin",
      "project_id": null,
      "ip": "192.168.1.1",
      "details": {}
    }
  ],
  "count": 1
}

Bekannte Aktionen:

• user.login — Erfolgreicher Login
• user.create — Benutzer angelegt
• user.delete — Benutzer gelöscht
• user.password_change — Passwort geändert
• agent.create — Agent angelegt
• agent.update — Agent bearbeitet
• agent.delete — Agent gelöscht
• project.create — Projekt angelegt
• project.provision — Projekt provisioniert
• project.delete — Projekt gelöscht
• skill.create — Skill angelegt
• skill.update — Skill bearbeitet
• skill.delete — Skill gelöscht
• webhook.create — Webhook angelegt
• webhook.delete — Webhook gelöscht
• webhook.trigger — Webhook ausgelöst
• llm.token_set — LLM-Token gesetzt

LLM-Konfiguration

GET/llm/config

Gibt die aktuelle LLM-Konfiguration zurück (alle Anbieter).

PUT/llm/config/claude_max

Setzt den Claude Max OAuth-Token.

{ "token": "sk-ant-oat01-..." }

PUT/llm/config/{provider}

Konfiguriert einen beliebigen LLM-Anbieter (z.B. openai, ollama).

GET/llm/claude_token_status

Gibt den Status des aktuellen Claude-Tokens zurück.

Response 200:

{
  "exists": true,
  "remaining_days": 12,
  "expires_approx": "2026-04-01",
  "status": "ok"
}

GET/llm/ollama/models

Gibt eine Liste der lokal verfügbaren Ollama-Modelle zurück.

POST/llm/ollama/pull

Lädt ein Ollama-Modell herunter.

{ "model": "llama3.1:8b" }

Tools

GET/tools

Gibt eine Liste aller registrierten Tools mit ID, Beschreibung und Parameter-Schema zurück.

System-Logs

GET/logs/core

Gibt die letzten Zeilen der Core-Logs zurück.

GET/logs/core/summary

Gibt eine verdichtete Core-Journal-Zusammenfassung mit ERROR/WARN-Zählung und Signaturen zurück.