OctopOS 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": { ... }
}

Gitea & Git Tools

GET/gitea/config

Gibt URL, Organisation, Webhook-Secret und maskierten Token zurück.

PUT/gitea/config

Schreibt neue Gitea-URL/org/Token (Admin only). Token-Datei wird auf 600 gelegt.

GET/gitea/repos

Listet Repositories der Organisation oder des Users.

GET/gitea/repos/{project_id}/prs

Gibt offene Pull Requests eines Projekts zurück.

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.

Personal Agent

Endpoints unter /me/agent betreffen den persönlichen Agenten inklusive Execution Modes und Tools.

GET/me/agent

Gibt die Konfiguration (LLM, soul, tools, execution_modes) sowie den Runtime-Status zurück.

PUT/me/agent

Aktualisiert Identität, LLM und erlaubte Tools. Execution Modes: default (safe), elevated, root, nur Admin darf erhöhte Modi anfordern.

POST/me/agent/message/stream

Streamt die Antwort des persönlichen Agenten (SSE). Optionaler Parameter execution_mode (wird auditierbar protokolliert).

GET/me/agent/session/history

History der persönlichen Session, die zusammengefasste Kontextbotschaften enthält.

DELETE/me/agent/session

Leert die aktive Session (history wird persistiert) — Einsatz bei Reset oder Trainingsrestart.

Memory & A-MEM

Memory-Dateien liegen lokal unter /agents/{id}/memory/. A-MEM ist ein MCP-basierter Shared Memory-Server (Port 8020) für teamweite Erkenntnisse.

POST/agents/{agent_id}/memory

Speichert oder hängt Inhalt an eine Memory-Datei an. Parameter: filename, content, mode ("overwrite"/"append").

POST/agents/{agent_id}/session/compact

Komprimiert die Session via Claude (OAuth) und ersetzt alte Nachrichten durch eine Zusammenfassung zur Token-Kontrolle.

WKS / Discord / MCP

Externe Toolzugriffe über Workstation, Discord-Bot-Config oder MCP werden über eigene Endpoints behandelt.

GET/me/wks

Zeigt Workstation-IP, SSH-User, Ollama-Port und ob ein SSH-Key bekannt ist.

PUT/me/wks

Speichert WKS-Zugangsdaten und optional den SSH-Key.

GET/me/wks/ollama-models

Listet Modelle auf, die auf der konfigurierten Workstation verfügbar sind.

GET/me/discord

Zeigt Discord-Bot-Token, Guild und Channels.

PUT/me/discord

Aktualisiert Discord-Bot-Token, Guild-ID und Channels.

POST/me/discord/test

Sendet einen Test-Webhook an den eingerichteten Discord-Channel.

GET/mcp/servers

Listet alle MCP-Server (A-MEM, QMD, Custom) mit Transport und URL.

POST/admin/update/trigger

Startet den Self-Update-Prozess (Admin only). Antwort: {"status":"deploying"}.

GET/admin/update/status

Zeigt laufenden/neuesten Update-Status mit Commit-Hash und Log-Tail.

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.

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.178.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.