REST-API und Webhooks
API-Schlüssel erzeugen, die REST-API von Agile Storage nutzen und Ereignisse per Webhook empfangen.
Dokumentation
Die API-Dokumentation steht unter https://storage.agiledeveloper.de/docs, die Spezifikation unter https://storage.agiledeveloper.de/api/openapi.json. In der App erreichen Sie sie über das Kontomenü und API und MCP.
API-Schlüssel erzeugen
- Öffnen Sie Einstellungen → Entwickler (API).
- Tragen Sie unter API-Schlüssel einen Namen ein und setzen Sie auf Wunsch ein Datum bei Läuft ab (optional).
- Wählen Sie die Rechte.
- Klicken Sie auf Schlüssel erzeugen und kopieren Sie ihn. Der Schlüssel erscheint nur einmal.
Über Widerrufen in der Liste machen Sie einen Schlüssel ungültig.
Die Rechte
dateien:lesen: Dateien und Ordner auflisten, suchen, herunterladen, Versionen und Papierkorb ansehen.dateien:schreiben: Hochladen, Ordner anlegen, umbenennen, verschieben, kopieren, löschen, wiederherstellen.freigaben:verwalten: Mit Personen und Teams teilen, Links anlegen und widerrufen.teams:verwalten: Teams anlegen, Mitglieder einladen und entfernen.konto:lesen: Profil, Speicherplatz und Benachrichtigungen lesen.webhooks:verwalten: Webhooks anlegen, löschen und Zustellungen lesen.
Erster Aufruf
curl -H "Authorization: Bearer agile_sto_…" https://storage.agiledeveloper.de/api/v1/eintraege
Wichtige Regeln
- Rate-Limit: 300 Anfragen pro Minute je Schlüssel bzw. App. Bei Überschreitung antwortet die API mit 429 und
Retry-After. - Große Dateien: Laden Sie sie über
POST /api/v1/uploadsin Teilen hoch. - Konfliktschutz: Geben Sie beim Ändern die bekannte
version_idmit. Hat jemand die Datei inzwischen geändert, antwortet die API mit 409 und überschreibt nichts. - Wiederholungen: POST-Anfragen akzeptieren den Header
Idempotency-Key.
Webhooks einrichten
- Öffnen Sie Einstellungen → Entwickler (API).
- Tragen Sie unter Webhooks die Ziel-URL ein. Sie muss mit
https://beginnen. - Wählen Sie die Ereignisse und klicken Sie auf Webhook anlegen.
- Kopieren Sie das Signatur-Geheimnis. Es ist nur jetzt sichtbar.
Mit Test senden prüfen Sie die Zustellung, Protokoll zeigt die Zustellungen. Löschen entfernt den Webhook.
Ereignisse
datei.hochgeladen: Datei hochgeladendatei.geaendert: Datei geändert (neue Version, umbenannt, verschoben)datei.geloescht: In den Papierkorb gelegtordner.angelegt: Ordner angelegtfreigabe.erhalten: Etwas wurde mit Ihnen geteiltlink.upload: Upload über Ihren Upload-Linkspeicher.fast_voll: Speicher fast volltranskript.fertig: Transkript fertig
Signatur und Wiederholungen
Agile Storage schickt Ereignisse als signierten POST an Ihre Adresse. Der Header Agile-Signature hat die Form t=<unix>,v1=<hex>. v1 ist HMAC-SHA256 mit dem Webhook-Geheimnis über <t>.<body>.
Antworten Sie mit 2xx. Sonst wiederholt Agile Storage die Zustellung nach 1, 5, 30, 120, 360 und 1440 Minuten.