REST API Endpoints¶

Base URL: http://localhost:3001/api

Alle Endpoints (außer /auth/login, /health und /api/info) erfordern Authorization: Bearer <jwt-token>.

Authentication¶

POST /auth/login¶

Login — gibt ein JWT-Token zurück.

Request:

{ "email": "admin@fileflux.de", "password": "admin123" }

Response:

{ "token": "eyJhbG...", "user": { "id": 1, "email": "admin@fileflux.de", "role": "admin" } }

POST /auth/refresh¶

Erneuert ein JWT-Token.

GET /auth/user¶

Gibt den aktuellen Benutzer zurück.

POST /auth/password¶

Ändert das Passwort des aktuellen Benutzers.

Request:

{ "old_password": "oldpw", "new_password": "newpw" }

Agents¶

GET /agents¶

Alle Agenten auflisten.

POST /agents¶

Agent erstellen (Admin only).

Request:

{ "name": "prod-agent-01", "type": "server", "description": "Primary upload server" }

GET /agents/:id¶

Agent-Details abrufen.

PUT /agents/:id¶

Agent aktualisieren (Admin only).

DELETE /agents/:id¶

Agent löschen (Admin only).

POST /agents/:id/test¶

Verbindung zum Agent testen (Admin only).

Jobs¶

GET /jobs¶

Alle Jobs des Benutzers auflisten (gefiltert nach user_id).

POST /jobs¶

Neuen Job erstellen.

Request:

{
  "name": "Daily Report Transfer",
  "type": "push",
  "source_agent_id": 1,
  "destination_agent_id": 2,
  "source_path": "/data/reports/",
  "destination_path": "/incoming/reports/",
  "schedule": "0 0 6 * * *",
  "description": "Täglicher Report-Transfer um 06:00"
}

GET /jobs/:id¶

Job-Details (Ownership-Prüfung — nur eigene Jobs).

PUT /jobs/:id¶

Job aktualisieren (Ownership-Prüfung).

DELETE /jobs/:id¶

Job löschen (Ownership-Prüfung).

POST /jobs/:id/run¶

Job sofort ausführen (Ownership-Prüfung). Erstellt einen neuen Transfer und dispatcht ihn an den Quell-Agenten.

Transfers¶

GET /transfers¶

Alle Transfers des Benutzers auflisten (gefiltert nach user_id über Job-Zugehörigkeit).

POST /transfers¶

Neuen Transfer erstellen.

Request:

{
  "job_id": 1,
  "filename": "report.csv",
  "size": 1048576,
  "source_path": "/data/reports/report.csv",
  "destination_path": "/incoming/report.csv",
  "source_agent_id": 1,
  "destination_agent_id": 2
}

GET /transfers/:id¶

Transfer-Details (Ownership-Prüfung über Job-Zugehörigkeit).

POST /transfers/:id/cancel¶

Laufenden Transfer abbrechen (Ownership-Prüfung).

Tokens¶

GET /tokens¶

Alle Agent-Tokens auflisten.

POST /tokens¶

Neues Agent-Token erstellen (Admin only).

Request:

{ "name": "agent-prod-01", "agent_id": 1, "description": "Production agent token" }

Response:

{
  "token": { "id": 1, "name": "agent-prod-01", "agent_id": 1, "created_at": "...", "expires_at": null },
  "value": "ffx_abc123..."
}

Token-Wert wird nur einmal angezeigt

Der value wird nur bei der Erstellung zurückgegeben. Speichern Sie ihn sofort.

DELETE /tokens/:id¶

Token widerrufen (Admin only).

File Transfer (Agent-Authentifizierung)¶

Diese Endpoints nutzen Agent-Token (nicht JWT) im Authorization: Bearer <agent-token> Header. Sie werden vom Agent für den eigentlichen Dateitransfer verwendet.

PUT /files/:transferId/upload¶

Datei hochladen.

Query Parameter:

Param	Type	Default	Description
`filename`	string	`file.dat`	Dateiname

Request Body: Raw file bytes (application/octet-stream).

Limits: Max 5 GB Upload-Größe.

Response:

{ "transfer_id": 1, "filename": "report.csv", "size": 1048576, "agent_id": 3 }

GET /files/:transferId/download¶

Datei herunterladen.

Response: Datei als application/octet-stream mit Content-Disposition: attachment.

Health & Info¶

GET /health¶

Health-Check (keine Authentifizierung). Prüft Datenbank-Konnektivität.

Response (healthy):

{ "status": "ok", "version": "1.0.0", "components": { "database": "ok", "api": "ok" } }

Response (unhealthy, HTTP 503):

{ "status": "degraded", "version": "1.0.0", "components": { "database": "error", "api": "ok" } }

GET /api/info¶

API-Informationen.

{ "name": "FileFlux API", "version": "1.0.0", "docs": "/api/docs" }

Agent Long-Polling (Fallback)¶

Diese Endpoints werden vom Agent als Fallback-Transport genutzt, wenn keine WebSocket-Verbindung möglich ist. Authentifizierung erfolgt per Authorization: Bearer <agent-token>.

POST /api/agent/connect¶

Agent-Registrierung über Polling-Transport.

GET /api/agent/poll¶

Long-Polling — wartet auf neue Nachrichten vom Server.

POST /api/agent/messages¶

Agent sendet Nachrichten (Heartbeat, Transfer-Status) an den Server.

POST /api/agent/ack¶

Agent bestätigt den Empfang einer Nachricht.

Error Format¶

Alle Fehler folgen einem einheitlichen Format:

{ "error": "Beschreibung des Fehlers" }

HTTP Status	Bedeutung
400	Ungültige Anfrage / Validierungsfehler
401	Nicht authentifiziert
403	Unzureichende Berechtigungen
404	Ressource nicht gefunden (oder kein Zugriff)
413	Datei zu groß
429	Rate Limit überschritten
500	Interner Serverfehler

IDOR-Schutz

Alle Single-Resource-Endpoints (/jobs/:id, /transfers/:id) prüfen die Besitzverhältnisse. Zugriffe auf fremde Ressourcen geben 404 Not Found zurück — nicht 403 — um keine Informationen über die Existenz von Ressourcen preiszugeben.