Public API Dokumentation - cryptfiles.cloud

Developer API

Public API Dokumentation

Programmgesteuerter Zugriff auf deine Datei- und Ordner-Metadaten.

Base URL

https://cryptfiles.cloud/api/public/v1

Alle Endpunkte sind owner-gebunden. Ein Token kann nur Ressourcen des Accounts lesen/schreiben, der das Token erstellt hat. Hinweis: Uploads sind in der Public API aufgrund des Zero-Knowledge-Modells derzeit nicht verfügbar.

Bereiche

Quick Start

Erstelle ein Bearer-Token unter Dashboard -> Profil -> Public API Tokens.
Speichere das Token sicher. Das Klartext-Token wird nur einmal angezeigt.
Sende Requests mit `Authorization: Bearer {token}` und `Accept: application/json`.
Vergib nur die Scopes, die wirklich benötigt werden (Least Privilege).

Typische Status Codes

200 OK - Request erfolgreich
201 Created - Ressource erstellt
401 Unauthorized - Token fehlt/ungültig
403 Forbidden - Scope fehlt oder Account ist eingeschränkt
404 Not Found - Ressource für diesen Owner nicht sichtbar
422 Unprocessable Entity - Validierungsfehler
429 Too Many Requests - Rate Limit erreicht

Security-Modell

Token-Secrets werden serverseitig nie im Klartext gespeichert.
Strikte Owner-Prüfungen verhindern Cross-Account-Zugriffe auf Dateien/Ordner.
Suspendierte oder gesperrte Accounts werden für die Public API blockiert.
Wegen des Zero-Knowledge-Modells sind Upload-Endpunkte in der Public API nicht möglich.

Pflicht-Header

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json (bei JSON-Body)

Account

Profil-, Speicher- und Nutzungsstatistiken lesen.

GET /account Scope: account:read Account-Daten abrufen

Liefert Profil, Speicherquoten/-nutzung und aggregierte Statistiken des Token-Owners.

Request Details

Request-Hinweise

Kein Request-Body erforderlich.

Response-Felder

data.id: Account-UUID
data.name: Anzeigename des Profils
data.email: Account-E-Mail
data.account_type: Aktueller Tarif
data.storage.used_bytes: Gespeicherte Bytes
data.storage.pending_bytes: Für laufende Uploads reservierte Bytes
data.storage.quota_bytes: Maximal erlaubte Bytes
data.storage.available_bytes: Verbleibende Bytes
data.storage.usage_percentage: Speichernutzung in Prozent
data.stats.uploads_count: Gesamtzahl erfolgreicher Uploads
data.stats.downloads_count: Gesamtzahl erfolgreicher Downloads
data.stats.views_count: Gesamtzahl View-/Stream-Events
data.stats.shares_count: Gesamtzahl erstellter Share-Links
data.stats.files_count: Gesamtzahl in der Statistik geführter Dateien
data.stats.bandwidth_used_bytes: Gesamt übertragene Bandbreite in Bytes
data.fair_use.daily_bandwidth_used_bytes: Aktueller Fair-Use-Zähler für heute in Bytes
data.fair_use.full_speed_limit_bytes: Ab diesem Tageslimit beginnt die Drosselung
data.fair_use.heavy_throttle_from_bytes: Ab diesem Tageslimit startet starke Drosselung
data.fair_use.moderate_delay_ms: Chunk-Verzögerung bei moderater Drosselung
data.fair_use.heavy_delay_ms: Chunk-Verzögerung bei starker Drosselung
data.fair_use.current_delay_ms: Aktuell angewendete Chunk-Verzögerung
data.fair_use.current_state: full_speed|moderate|heavy

Hinweise

Immer owner-gebunden. Kein Cross-Account-Lookup möglich.
Alle Bandbreiten-Werte sind in Bytes.
Die Drosselung basiert auf täglichen Fair-Use-Bytes und Account-Tier.
Moderate Drosselung startet bei daily_bandwidth_used_bytes >= full_speed_limit_bytes; starke Drosselung bei >= heavy_throttle_from_bytes.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/account" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Dateien

Datei-Metadaten auflisten, lesen, aktualisieren, teilen und löschen.

GET /files Scope: files:read Datei-Metadaten auflisten

Gibt paginierte Datei-Metadaten für den Owner-Account zurück.

Request Details

Query-Parameter

folder_id (uuid optional)
status (uploading|processing|available|deleted optional)
is_video (boolean optional)
share_type (public|private optional)
per_page (integer 1-200 optional)

Response-Felder

data.items[].id
data.items[].folder_id, original_file_id, reference_count
data.items[].status, share_type, is_video, mime_type
data.items[].file_size, file_size_encrypted, chunk_size, chunk_count
data.items[].download_count, stream_count
data.items[].metadata, thumbnail_path, thumbnail_nonce
data.items[].created_at, updated_at, expires_at
data.pagination.current_page, last_page, per_page, total

Hinweise

Ohne status-Filter wird standardmäßig status=available genutzt.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/files?per_page=50" \
  -H "Authorization: Bearer {token}"

GET /files/{fileId} Scope: files:read Einzelne Datei-Metadaten lesen

Liefert Metadaten einer einzelnen Owner-Datei.

Request Details

Path-Parameter

fileId (uuid)

Response-Felder

data.id
data.folder_id, original_file_id, reference_count
data.status, share_type, is_video, mime_type
data.file_size, file_size_encrypted, chunk_size, chunk_count
data.download_count, stream_count
data.metadata, thumbnail_path, thumbnail_nonce
data.created_at, updated_at, expires_at

Hinweise

404, wenn die Datei nicht dem Token-Owner gehört.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/files/{file_id}" \
  -H "Authorization: Bearer {token}"

PATCH /files/{fileId} Scope: files:write Datei-Metadaten aktualisieren (kein Content)

Aktualisiert owner-sichtbare Metadaten wie Ordnerzuordnung, Share-Typ, Ablaufdatum und Metadaten.

Request Details

Path-Parameter

fileId (uuid)

Body-Parameter (JSON)

folder_id (uuid|null optional)
share_type (public|private optional)
is_video (boolean optional)
expires_at (date|null optional)
metadata (string|null optional)

Response-Felder

Gleiches Dateiobjekt wie bei GET /files/{fileId}

Hinweise

folder_id muss zum selben Owner gehören.
Dateiinhalt wird von diesem Endpunkt nicht geändert.
Wenn kein änderbares Feld übergeben wird, liefert der Endpunkt 422.

Beispiel

curl -X PATCH "https://cryptfiles.cloud/api/public/v1/files/{file_id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"share_type":"private"}'

DELETE /files/{fileId} Scope: files:write Datei löschen

Löscht eine Datei mit Owner-Autorisierung und bestehender sicherer Löschlogik.

Request Details

Path-Parameter

fileId (uuid)

Response-Felder

success
message

Hinweise

404 für nicht sichtbare/nicht-eigene Ressourcen.

Beispiel

curl -X DELETE "https://cryptfiles.cloud/api/public/v1/files/{file_id}" \
  -H "Authorization: Bearer {token}"

POST /files/{fileId}/share Scope: files:write Datei-Share-Link erstellen

Erstellt ein Share-Token für eine Owner-Datei.

Request Details

Path-Parameter

fileId (uuid)

Body-Parameter (JSON)

password (string min 4 optional)
max_downloads (integer >= 1 optional)
expires_in_days (integer 1-365 optional)

Response-Felder

data.share_id, share_token, share_url
data.expires_at, has_password
message

Hinweise

Owner-only Endpunkt.

Beispiel

curl -X POST "https://cryptfiles.cloud/api/public/v1/files/{file_id}/share" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"max_downloads":25}'

Ordner

Ordnerstruktur entsprechend des bestehenden Systems erstellen und verwalten.

GET /folders Scope: folders:read Ordner auflisten

Gibt Ordner im Flat- oder Tree-Format zurück.

Request Details

Query-Parameter

format (flat|tree optional default flat)

Response-Felder

data[].id, parent_folder_id, name, display_order
data[].created_at, updated_at, deleted_at
data[].file_count, subfolder_count, object_count
data[].children[] (nur bei format=tree, rekursiv gleiche Felder)

Hinweise

Ergebnisse sind immer owner-gebunden.
Ungültige format-Werte liefern 422-Validierungsfehler.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/folders?format=tree" \
  -H "Authorization: Bearer {token}"

GET /folders/{folderId} Scope: folders:read Ordner-Details lesen

Liefert Ordner-Metadaten plus Breadcrumb-Pfad.

Request Details

Path-Parameter

folderId (uuid)

Response-Felder

data.folder.id, parent_folder_id, name, display_order
data.folder.created_at, updated_at, deleted_at
data.folder.file_count, subfolder_count, object_count
data.breadcrumbs[] mit gleichen Ordnerfeldern

Hinweise

404 für nicht-eigene Ordner.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/folders/{folder_id}" \
  -H "Authorization: Bearer {token}"

POST /folders Scope: folders:write Ordner erstellen

Erstellt einen neuen Ordner in der vorhandenen Hierarchie.

Request Details

Body-Parameter (JSON)

name (required nicht leerer String)
parent_folder_id (uuid|null optional)
display_order (integer >= 0 optional)

Response-Felder

data.id, parent_folder_id, name, display_order
data.created_at, updated_at, deleted_at
data.file_count, subfolder_count, object_count

Hinweise

parent_folder_id muss zum Owner-Account gehören.

Beispiel

curl -X POST "https://cryptfiles.cloud/api/public/v1/folders" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Projekt Alpha"}'

PATCH /folders/{folderId} Scope: folders:write Ordner-Metadaten aktualisieren

Benennt um, verschiebt oder sortiert einen vorhandenen Ordner neu.

Request Details

Path-Parameter

folderId (uuid)

Body-Parameter (JSON)

name (nicht leerer String optional)
parent_folder_id (uuid|null optional)
display_order (integer >= 0 optional)

Response-Felder

data.id, parent_folder_id, name, display_order
data.created_at, updated_at, deleted_at
data.file_count, subfolder_count, object_count

Hinweise

Das Ziel bei Verschiebungen muss dem Owner gehören.
Wenn kein änderbares Feld übergeben wird, liefert der Endpunkt 422.
Ungültige Moves (in sich selbst/Nachfolger) liefern 422.

Beispiel

curl -X PATCH "https://cryptfiles.cloud/api/public/v1/folders/{folder_id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"display_order":3}'

DELETE /folders/{folderId} Scope: folders:write Ordner löschen

Löscht einen Ordner.

Request Details

Path-Parameter

folderId (uuid)

Response-Felder

success
message

Hinweise

404 für nicht-eigene Ordner.

Beispiel

curl -X DELETE "https://cryptfiles.cloud/api/public/v1/folders/{folder_id}" \
  -H "Authorization: Bearer {token}"

Suche

Eigene Dateien und Ordner durchsuchen.

GET /search Scope: search:read Dateien und Ordner durchsuchen

Durchsucht owner-eigene Ressourcen per Query.

Request Details

Query-Parameter

q (required 1-200 Zeichen)
type (all|files|folders optional)
limit (integer 1-100 optional)

Response-Felder

data.query
data.files[] mit gleichen Datei-Feldern wie GET /files/{fileId}
data.folders[] mit gleichen Ordner-Feldern wie GET /folders/{folderId}.data.folder

Hinweise

Suche ist immer auf Ressourcen des Token-Owners begrenzt.

Beispiel

curl -X GET "https://cryptfiles.cloud/api/public/v1/search?q=video&type=files&limit=20" \
  -H "Authorization: Bearer {token}"