🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowDrive API - für Dateien, Ordner und Freigaben

Eine vollständige REST API für den Dateispeicher. Sie deckt Ablage und Suche, Upload in zwei Varianten, zeitlich begrenzte Abruflinks, öffentliche Freigaben, geteilte Drives mit Rechtestufen und drei Auswertungen ab.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowdrive/context https://creativeskyline.de/api/flowdrive/entries https://creativeskyline.de/api/flowdrive/drives https://creativeskyline.de/api/flowdrive/share-links https://creativeskyline.de/api/flowdrive/reports
FlowDrive-Berechtigung erforderlich
Der Benutzer benötigt eine aktive FlowDrive-Berechtigung (fd). Ist das Modul in den Teameinstellungen abgeschaltet, antwortet jede Route mit HTTP 403.
Alles wird über UUIDs adressiert
Jeder Eintrag, jedes geteilte Drive und jeder Freigabelink wird ausschließlich über seine UUID angesprochen. Numerische Felder wie parent_id oder client_id werden nicht mehr entgegengenommen und führen zu einem Validierungsfehler, der das Ersatzfeld benennt.

1. API-Zugangsdaten abrufen

Melden Sie sich an, öffnen Sie Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Authentifizierung

Alle Anfragen benötigen diese HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

3. Einstieg

Beginnen Sie mit GET /api/flowdrive/context. Die Antwort nennt die verfügbaren Bereiche, alle geteilten Drives samt Ihrer eigenen Rechtestufe, den belegten Speicher und die geltenden Upload-Grenzen.

4. Rechte im Überblick

Geteilte Drives kennen drei Stufen: view liest, edit legt an, benennt um und verschiebt, manage verwaltet zusätzlich Mitglieder, Freigaben und den Papierkorb. Private Einträge ohne Bezug zu Kunde, Projekt oder Kontakt gehören ausschließlich ihrem Ersteller.

🧭 Überblick

Bereiche, geteilte Drives und Grenzen abrufen

GET /api/flowdrive/context

Liefert die adressierbaren Bereiche (personal, shared_drive, client, project, contact), alle geteilten Drives mit der eigenen Rechtestufe, den belegten Speicher des Teams sowie die Upload-Grenzen und die zugelassenen Dateiendungen.

📄 Einträge lesen

Ordnerebene oder Suche
Ohne "search" liefert die Liste genau eine Ordnerebene: den über "parent_uuid" genannten Ordner, sonst die oberste Ebene des gewählten Bereichs. Mit "search" wird "parent_uuid" ignoriert und der gesamte Bereich nach Namen durchsucht.

Einträge auflisten oder suchen

GET /api/flowdrive/entries

Listet Ordner, Dateien und externe Verlinkungen. Sichtbar sind eigene private Einträge, Einträge an Kunden, Projekten und sichtbaren Kontakten sowie die Inhalte der geteilten Drives, auf denen eine Berechtigung besteht. Ordner stehen vor Dateien, danach wird alphabetisch sortiert.

Query-Parameter:

scope string personal, shared_drive, client, project oder contact. Ohne Angabe wird über alle sichtbaren Bereiche gelesen.
scope_uuid string UUID des geteilten Drives, Kunden, Projekts oder Kontakts. Pflicht für alle Bereiche außer personal.
parent_uuid string UUID des Ordners, dessen Inhalt gelistet wird. Ohne Angabe wird die oberste Ebene geliefert.
search string Sucht im gesamten Bereich nach Namensbestandteilen und übergeht dabei parent_uuid.
kind string Auf folder, file oder link einschränken.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitennummer, Standard 1.

Einzelnen Eintrag abrufen

GET /api/flowdrive/entries/{uuid}

Liefert einen Eintrag samt Pfad vom obersten Ordner seines Bereichs bis zu ihm selbst. Eine UUID aus einem fremden Team wird wie eine unbekannte UUID mit HTTP 404 beantwortet.

Extrahierten Text einer Datei abrufen

GET /api/flowdrive/entries/{uuid}/content

Liefert den bereits indexierten Text einer Datei, also denselben Text, den die KI-Werkzeuge lesen. Es wird nichts neu ausgelesen: Ist die Datei noch nicht indexiert, ist "indexed" false und "text" leer. Für Ordner antwortet die Route mit HTTP 422.

Zeitlich begrenzten Abruflink erzeugen

GET /api/flowdrive/entries/{uuid}/download-url

Erzeugt eine vorsignierte Adresse direkt auf die gespeicherten Bytes. Die Gültigkeitsdauer steht in "expires_at". Dateitypen, die ein Browser ausführen kann (svg, html, xml), werden über signierte Kopfzeilen stets als Download ausgeliefert und nie eingebettet dargestellt. Bei einer externen Verlinkung wird deren Zieladresse mit "expires_at": null geliefert.

Datei direkt herunterladen

GET /api/flowdrive/entries/{uuid}/download BINARY

Liefert die Datei zum Herunterladen. Liegt sie im Objektspeicher, antwortet die Route mit einer Weiterleitung (HTTP 302) auf die vorsignierte Adresse, damit die Bytes nicht durch die Anwendung laufen; folgen Sie dieser Weiterleitung. Für Ordner und externe Verlinkungen antwortet die Route mit HTTP 422.

✏️ Einträge anlegen und ändern

Wo ein neuer Eintrag landet
Ist "parent_uuid" gesetzt, übernimmt der neue Eintrag den Bereich des Ordners und alle weiteren Angaben werden nicht benötigt. Ohne Ordner entscheidet genau eine der Angaben client_uuid, project_uuid, contact_uuid oder shared_drive_uuid; fehlt auch die, entsteht ein privater Eintrag des Aufrufers.

Ordner anlegen

POST /api/flowdrive/folders

Legt einen Ordner an. Besteht der Name am Zielort bereits, wird automatisch eine Zählung angehängt. Der Name ist auf 240 Zeichen begrenzt, damit diese Zählung und Umlaute noch Platz haben.

Request Body:

name string * Name des Ordners, höchstens 240 Zeichen.
description string Freitext, höchstens 2000 Zeichen.
parent_uuid string UUID des übergeordneten Ordners.
client_uuid string UUID des Kunden, an dem der Ordner hängt.
project_uuid string UUID des Projekts, an dem der Ordner hängt.
contact_uuid string UUID des Kontakts, an dem der Ordner hängt.
shared_drive_uuid string UUID des geteilten Drives. Erfordert mindestens die Stufe edit.
POST /api/flowdrive/external-links

Legt eine Verlinkung auf eine fremde Adresse an. Zugelassen sind ausschließlich http- und https-Adressen; alles andere wird mit HTTP 422 abgewiesen.

Request Body:

name string * Anzeigename, höchstens 240 Zeichen.
url string * Zieladresse, nur http oder https, höchstens 2048 Zeichen.
description string Freitext, höchstens 2000 Zeichen.
parent_uuid string UUID des übergeordneten Ordners.
client_uuid string UUID des Kunden.
project_uuid string UUID des Projekts.
contact_uuid string UUID des Kontakts.
shared_drive_uuid string UUID des geteilten Drives.

Datei direkt hochladen

POST /api/flowdrive/entries

Multipart-Upload für kleine Dateien. Die Obergrenze nennt "limits.direct_upload_max_bytes" im Überblick und liegt deutlich unter der Grenze des vorsignierten Wegs, weil diese Bytes durch die Anwendung laufen. Größere Dateien gehen über Upload-Adresse und Bestätigung.

Request Body:

file file * Die Datei selbst. Die Endung muss in der Positivliste stehen, die der Überblick ausgibt.
description string Freitext, höchstens 2000 Zeichen.
parent_uuid string UUID des Zielordners.
client_uuid string UUID des Kunden.
project_uuid string UUID des Projekts.
contact_uuid string UUID des Kontakts.
shared_drive_uuid string UUID des geteilten Drives.

Upload-Adresse anfordern

POST /api/flowdrive/entries/upload-url

Schritt eins des vorsignierten Uploads. Liefert eine Adresse, an die die Datei per HTTP PUT gesendet wird; die Bytes laufen dabei nie durch die Anwendung. Größe und Dateiendung werden geprüft, bevor eine Adresse ausgegeben wird. Der gespeicherte Inhaltstyp wird serverseitig aus dem Dateinamen abgeleitet, ein übergebener "mime_type" wird dafür bewusst nicht verwendet.

Request Body:

name string * Dateiname mit Endung, höchstens 240 Zeichen.
size integer * Größe in Bytes.
mime_type string Nur informativ; der gespeicherte Inhaltstyp wird aus der Dateiendung abgeleitet.
parent_uuid string UUID des Zielordners. Wird bereits hier geprüft.
client_uuid string UUID des Kunden.
project_uuid string UUID des Projekts.
contact_uuid string UUID des Kontakts.
shared_drive_uuid string UUID des geteilten Drives.

Upload bestätigen

POST /api/flowdrive/entries/confirm

Schritt zwei des vorsignierten Uploads. Der Schlüssel muss zum eigenen Team gehören, das Objekt muss bereits im Speicher liegen, und die tatsächliche Länge im Speicher hat Vorrang vor der gemeldeten Größe. Ein bereits bestätigter Schlüssel liefert den vorhandenen Eintrag zurück statt eines zweiten.

Request Body:

s3_key string * Der Schlüssel aus der Antwort der Upload-Adresse.
name string * Angezeigter Dateiname, höchstens 240 Zeichen.
size integer Nur informativ; maßgeblich ist die Länge im Speicher.
mime_type string Nur informativ; abgeleitet wird aus der Dateiendung.
description string Freitext, höchstens 2000 Zeichen.
parent_uuid string UUID des Zielordners.
client_uuid string UUID des Kunden.
project_uuid string UUID des Projekts.
contact_uuid string UUID des Kontakts.
shared_drive_uuid string UUID des geteilten Drives.

Eintrag umbenennen

PUT /api/flowdrive/entries/{uuid}

Ändert Namen und Beschreibung. Ein Ortswechsel ist eine eigene Aktion. Kollidiert der neue Name am selben Ort, wird eine Zählung angehängt. Erfordert die Stufe edit.

Request Body:

name string Neuer Name, höchstens 240 Zeichen.
description string Neuer Freitext, höchstens 2000 Zeichen.

Eintrag verschieben

POST /api/flowdrive/entries/{uuid}/move

Verschiebt einen Eintrag in einen anderen Ordner oder, mit "parent_uuid": null, auf die oberste Ebene seines bisherigen Bereichs. Ordner nehmen ihren gesamten Inhalt mit. Das Feld ist ausdrücklich anzugeben, weil ein Weglassen nicht von einem gewollten Verschieben nach oben zu unterscheiden wäre.

Request Body:

parent_uuid string * UUID des Zielordners oder null für die oberste Ebene. Das Ziel muss ein Ordner sein und die Stufe edit erfordern.

🗑️ Papierkorb

Endgültiges Löschen ist unumkehrbar
Das Verschieben in den Papierkorb lässt die Bytes im Speicher liegen. Erst das endgültige Löschen entfernt sie; danach gibt es keinen Weg zurück.

Eintrag in den Papierkorb legen

DELETE /api/flowdrive/entries/{uuid}

Legt einen Eintrag samt allem darunter in den Papierkorb. Erfordert die Stufe manage. Systemordner und Einträge, die noch in einem Newsletter verwendet werden, werden abgewiesen.

Eintrag wiederherstellen

POST /api/flowdrive/entries/{uuid}/restore

Holt einen Eintrag samt allem darunter aus dem Papierkorb zurück. Erfordert die Stufe manage. Liegt der Eintrag nicht im Papierkorb, antwortet die Route mit HTTP 422.

Eintrag endgültig löschen

DELETE /api/flowdrive/entries/{uuid}/purge

Löscht einen Eintrag im Papierkorb endgültig und entfernt die gespeicherten Bytes. Erfordert die Stufe manage. Liegt der Eintrag nicht im Papierkorb, antwortet die Route mit HTTP 422.

👥 Geteilte Drives

Drei Rechtestufen
view liest, edit legt an, benennt um und verschiebt, manage verwaltet zusätzlich Mitglieder, Freigaben, Papierkorb und das Drive selbst. Der Ersteller hat manage von Anfang an. Es gibt keine Sonderrolle für Teaminhaber.

Geteilte Drives auflisten

GET /api/flowdrive/drives

Listet alle geteilten Drives, auf die der Aufrufer Zugriff hat, jeweils mit der eigenen Rechtestufe.

Geteiltes Drive anlegen

POST /api/flowdrive/drives

Legt ein geteiltes Drive an. Der Aufrufer erhält sofort die Stufe manage.

Request Body:

name string * Name des Drives, höchstens 255 Zeichen.

Geteiltes Drive abrufen

GET /api/flowdrive/drives/{uuid}

Liefert ein einzelnes geteiltes Drive samt eigener Rechtestufe. Erfordert mindestens die Stufe view.

Geteiltes Drive umbenennen

PUT /api/flowdrive/drives/{uuid}

Benennt ein geteiltes Drive um. Erfordert die Stufe manage.

Request Body:

name string * Neuer Name, höchstens 255 Zeichen.

Geteiltes Drive löschen

DELETE /api/flowdrive/drives/{uuid}

Löscht ein geteiltes Drive. Die enthaltenen Einträge bleiben samt ihrer Bytes bestehen, sind danach aber nicht mehr erreichbar. Erfordert die Stufe manage.

Mitglieder eines geteilten Drives auflisten

GET /api/flowdrive/drives/{uuid}/members

Listet alle Mitglieder mit ihrer Rechtestufe. Erfordert mindestens die Stufe view.

Mitglied hinzufügen oder Stufe ändern

POST /api/flowdrive/drives/{uuid}/members

Fügt ein Mitglied hinzu oder ändert dessen Stufe; beides ist derselbe Aufruf. Der Benutzer muss zum Team gehören, sonst antwortet die Route mit HTTP 404. Erfordert die Stufe manage.

Request Body:

user_uuid string * UUID des Teammitglieds.
level string * view, edit oder manage.

Mitglied entfernen

DELETE /api/flowdrive/drives/{uuid}/members/{userUuid}

Entzieht einem Mitglied den Zugriff. Das letzte verwaltende Mitglied kann sich nicht selbst entfernen, weil das Drive sonst herrenlos wäre; dieser Fall antwortet mit HTTP 422. Erfordert die Stufe manage.

📊 Auswertungen

Belegten Speicher abrufen

GET /api/flowdrive/reports/storage

Nennt den belegten Speicher des Teams in Bytes, aufgeteilt nach geteilten Drives und Einträgen an Kunden oder Projekten, dazu die Anzahl der Dateien. Die Zahlen gelten für das ganze Team, nicht für den einzelnen Benutzer.

Papierkorb auflisten

GET /api/flowdrive/reports/trash

Listet die Einträge im Papierkorb, neueste zuerst, eingeschränkt auf das, was der Aufrufer sehen darf. Statt einer Gesamtzahl meldet die Antwort "has_more", weil die Sichtbarkeit je Eintrag entschieden wird.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 20.
page integer Seitennummer, Standard 1.

Alle Freigabelinks auflisten

GET /api/flowdrive/reports/shares

Listet jeden öffentlichen Link des Teams, dessen zugehörigen Eintrag der Aufrufer sehen darf. Gedacht für die regelmäßige Durchsicht: welche Dateien sind derzeit ohne Anmeldung erreichbar.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 20.
page integer Seitennummer, Standard 1.