REST-API

Der Selu-Orchestrator stellt standardmäßig auf Port 8080 eine REST-API bereit. Alle Endpunkte erfordern Authentifizierung per Bearer-Token, sofern nicht anders angegeben.

Basis-URL

http://localhost:8080/api/v1

Setze SELU_API_BASE_URL, wenn der Orchestrator hinter einem Reverse Proxy läuft und du die Basis-URL überschreiben musst.

Authentifizierung

Gib dein API-Token im Header Authorization mit:

Authorization: Bearer <your-api-token>

Ein Token erzeugst du mit selu token create oder im Dashboard unter Settings → API Tokens.

Überblick über die Endpunkte

Methode	Pfad	Beschreibung
GET	/agents	Listet alle installierten Agenten auf
GET	/agents/{name}	Liefert Details zu einem bestimmten Agenten
POST	/agents	Installiert einen neuen Agenten aus einer Registry oder einem lokalen Pfad
DELETE	/agents/{name}	Deinstalliert einen Agenten und entfernt seinen Container
POST	/agents/{name}/restart	Startet den Laufzeit-Container eines Agenten neu
GET	/capabilities	Listet alle registrierten Capabilities auf
GET	/capabilities/{name}	Liefert Details und Manifest einer Capability
GET	/channels	Listet konfigurierte Kanäle auf
POST	/channels	Fügt eine neue Kanalkonfiguration hinzu
DELETE	/channels/{id}	Entfernt einen Kanal
POST	/conversations	Startet ein neues Gespräch mit einem Agenten
POST	/conversations/{id}/messages	Sendet eine Nachricht in einem bestehenden Gespräch
GET	/conversations/{id}	Holt den Gesprächsverlauf
GET	/health	Gesundheitsstatus des Orchestrators, ohne Authentifizierung

Beispiel: Agenten auflisten

Anfrage

curl -s http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer $SELU_TOKEN"

Antwort

{
  "agents": [
    {
      "name": "research-assistant",
      "version": "1.2.0",
      "status": "running",
      "channels": ["web", "telegram"],
      "capabilities": ["web-search", "file-writer"]
    }
  ]
}

Beispiel: Nachricht senden

Anfrage

curl -s -X POST http://localhost:8080/api/v1/conversations/conv_abc123/messages \
  -H "Authorization: Bearer $SELU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize the latest news on AI regulation."}'

Antwort

{
  "message_id": "msg_def456",
  "role": "assistant",
  "content": "Here is a summary of recent AI regulation developments...",
  "capabilities_used": ["web-search"],
  "timestamp": "2026-03-03T10:15:30Z"
}

Hinweis

Vollständige OpenAPI-Spezifikationen werden automatisch erzeugt und stehen unter /api/v1/openapi.json bereit, wenn der Orchestrator läuft. Du kannst diese Datei in Tools wie Swagger UI oder Redocly importieren, um die API interaktiv zu erkunden.

Fehlerformat

Alle Fehler verwenden eine einheitliche Struktur:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent 'foo' is not installed.",
    "request_id": "req_789xyz"
  }
}

Es gelten die üblichen HTTP-Statuscodes: 400 für Validierungsfehler, 401 für fehlende oder ungültige Authentifizierung, 404 für unbekannte Ressourcen und 500 für interne Fehler.