API Dazr Files: dokumentace pro vývojáře

Čtěte soubory z Dazr Files ve vlastním softwaru, například kvůli zálohování: REST API s kanálem změn a WebDAV pro zálohovací nástroje. Jen čtení.

• Rychlý start
• Přístup organizace
• Vlastní soubory osoby
• Reference
• Přírůstkové zálohy
• Chyby a limity
• WebDAV

Rychlý start

1. Zaregistrujte aplikaci a zapněte API Dazr Files. Zaregistrujte aplikaci, nebo použijte existující, v konzoli Dazr Identity: na stejném místě jako přihlášení přes Dazr Identity a API Dazr Sign, se stejným Client ID a tajným klíčem. Na stránce aplikace zvolte Zapnout API Dazr Files. Pro zálohy bez obsluhy musí jít o aplikaci webového serveru (s tajným klíčem klienta).
2. Získejte schválení. Dejte organizaci své Client ID. Vlastník nebo administrátor otevře Dazr Identity → Organizace → organizace → Propojené aplikace pro Files, zadá Client ID a vybere, co smí vaše aplikace číst: všechny sdílené soubory, nebo vybrané složky se vším, co obsahují. Může také aplikaci omezit na uvedené sítě (rozsahy IP).
3. Získejte token. Váš server si vyžádá token s grant_type=client_credentials, id organizace jako org a vaším Client ID a tajným klíčem (HTTP Basic nebo tělo formuláře). Mohou to jen aplikace s tajným klíčem klienta.
4. Zavolejte API. Posílejte přístupový token jako Authorization: Bearer. Platí 10 minut a refresh token neexistuje: když vyprší, vyžádejte si nový.

curl -u "$DAZR_CLIENT_ID:$DAZR_CLIENT_SECRET" https://identity.dazr.eu/oauth/token \
  -d grant_type=client_credentials -d scope=files.read -d org=org_3k9x2m0q8w1v5t7a

{ "access_token": "eyJhbGciOiJFUzI1NiIs...", "token_type": "Bearer", "expires_in": 600, "scope": "files.read" }

curl -H "Authorization: Bearer $TOKEN" https://suite.dazr.eu/api/files/v1/spaces

Přístup organizace pro zálohy

Jsou dvě cesty. Vlastník nebo administrátor organizace schválí vaši aplikaci pro sdílené soubory organizace a váš server pak dostává tokeny bez osoby (nejlepší pro zálohy bez obsluhy). Nebo osoba povolí vaší aplikaci scope files.read a aplikace čte vlastní soubory této osoby.

Organizace, která vaši aplikaci neschválila, organizace, která schválení odvolala, i organizace, která neexistuje, odpoví stejně: invalid_grant. Administrátoři vidí, kdy byla aplikace naposledy použita, a každý soubor, který stáhla, a mohou kdykoli změnit její složky nebo ji odvolat. Odvolané schválení skončí při dalším požadavku: již vydané tokeny okamžitě přestanou fungovat, stejně jako již vydané odkazy ke stažení. Vlastní soubory členů nejsou nikdy součástí schválení organizace.

Vlastní soubory osoby

Požádejte o openid files.read (a offline_access pro refresh token) v obvyklém toku authorization code s PKCE. Osoba na obrazovce souhlasu uvidí, že vaše aplikace smí její soubory zobrazit a stáhnout. Token dosáhne na její vlastní soubory a na sdílené soubory organizace jen tehdy, když vaši aplikaci schválila i tato organizace a osoba je členem, který je smí otevřít, se stejnými složkami. Když osoba aplikaci odebere v Propojených aplikacích, tokeny přestanou fungovat.

Reference

Základní URL https://suite.dazr.eu/api/files/v1. Každý endpoint je GET (a HEAD); jakákoli jiná metoda odpoví 405. Chyby jsou v JSON: { "error": { "code", "message" } }. Seznamy berou limit (1 až 1000, výchozí 200) a vracejí next_cursor, dokud je co načíst.

Každý požadavek potřebuje scope files.read. Parametry dotazu:

GET /spaces
{ "spaces": [ { "id": "org_3k9x2m0q8w1v5t7a", "type": "organisation", "name": "Bakkerij Jansen", "folders": "chosen" } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/folders/root/children?limit=2
{ "items": [
    { "id": "Hk2mQ9xP4aL1", "type": "folder", "name": "Finance", "parent_id": null, "path": "/Finance",
      "created_at": "2026-09-01T08:12:40.000Z" },
    { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "parent_id": "Hk2mQ9xP4aL1",
      "path": "/Finance/Budget 2027.xlsx", "size": 48213,
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "version": 3, "version_count": 3,
      "etag": "\"p3RtY7uW0zQe.3.48213\"", "sha256": null, "created_at": "2026-09-02T10:00:00.000Z",
      "modified_at": "2026-10-14T16:31:09.000Z", "trashed_at": null } ],
  "next_cursor": "o.2" }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/versions
{ "versions": [ { "version": 3, "size": 48213, "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                  "created_at": "2026-10-14T16:31:09.000Z", "current": true, "restored_from": null } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content
302 Found
Location: https://files.dazr.eu/v1/file?t=g1.…

curl -L -o "Budget 2027.xlsx" -H "Authorization: Bearer $TOKEN" \
  https://suite.dazr.eu/api/files/v1/spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content

Následujte přesměrování (curl -L): odkaz na files.dazr.eu nepotřebuje hlavičku Authorization. Soubor, který ještě není v bráně Files, se streamuje přímo místo přesměrování.

Kontrolní součty: Dazr Files neukládá hash obsahu jednotlivých souborů, proto je sha256 vždy null. etag se změní pokaždé, když se změní obsah (nová verze). Pokud hash potřebujete, spočítejte si ho při stahování. Soubory jsou uloženy šifrovaně (AES-256-GCM, s klíčem pro každý prostor, který spravuje Dazr) a Dazr je dešifruje, když je stahujete přes TLS. Nejde o end-to-end šifrování.

Přírůstkové zálohy

Zavolejte changes poprvé bez kurzoru: každá složka a soubor se vrátí jako created, spolu s cursor. Kurzor si uložte a příště ho pošlete jako cursor=. Dostanete, co se mezitím změnilo: created, updated (nový obsah), moved (přejmenováno nebo přesunuto do jiné složky), trashed, restored a deleted (trvale smazáno, nebo už mimo složky, které aplikace smí číst). Každá změna má id, item_type a aktuální item (null u smazaných). Složky jsou před soubory, rodiče před dětmi. Dokud je has_more true, volejte znovu s novým kurzorem. Když se nic nezměnilo, dostanete stejný kurzor. Kurzor platí 90 dní, jen pro vaši aplikaci a daný prostor; vypršelý odpoví 410 a začnete znovu bez kurzoru. Platných zůstává jen 5 nejnovějších kurzorů vaší aplikace pro daný prostor.

GET /spaces/org_3k9x2m0q8w1v5t7a/changes?cursor=dc1.ds_…
{ "changes": [
    { "type": "updated", "id": "p3RtY7uW0zQe", "item_type": "file",
      "item": { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "version": 4, … } },
    { "type": "deleted", "id": "Zx81LmQa2bNc", "item_type": "file", "item": null } ],
  "cursor": "dc1.ds_…",
  "has_more": false }

Chyby a limity

Chyby mají stav HTTP a tělo jako { "error": { "code": "not_found", "message": "..." } }. Vše, na co token nedosáhne, odpoví 404, stejně jako něco, co neexistuje.

Endpoint tokenu odpovídá chybami OAuth: invalid_client (nesprávné Client ID nebo tajný klíč, nebo aplikace bez tajného klíče klienta), unauthorized_client (API Dazr Files není pro aplikaci zapnuté), invalid_scope a invalid_grant (žádné schválení od této organizace, nebo ne z jejích uvedených sítí).

Každé stažení se pro administrátory organizace zaznamená s názvem aplikace, souborem, časem a částí IP adresy: posledních 5 000, až 180 dní. Stejný soubor stažený znovu do 10 minut se počítá jednou. Aktivita Files organizace ukazuje pro vaši aplikaci jeden řádek denně. Stažení z vlastních souborů osoby se zobrazí v jejích Propojených aplikacích.

WebDAV

Pro zálohovací nástroje, které umí WebDAV, vytvoří administrátor organizace pro vaši aplikaci přihlášení WebDAV v Propojených aplikacích pro Files. Heslo se zobrazí jednou, ukládá se jen jako hash a nikdy to není něčí heslo k Dazr. Přihlášení se řídí schválením: stejné složky, sítě a limity, a skončí, když je schválení odvoláno.

Názvy složek a souborů se zobrazují tak, jak jsou v Dazr Files. Když mají dvě položky ve složce stejný název (bez ohledu na velikost písmen), starší si ho ponechá a ostatní dostanou své id v závorce před příponou, aby měla každá položka vlastní cestu. Složku s více než 10 000 položkami nelze přes WebDAV vypsat; použijte pro ni API. Po 10 neúspěšných přihlášeních z jedné IP adresy během 15 minut tato adresa 15 minut čeká.

rclone

1. Spusťte rclone config, zvolte n pro nový remote, pojmenujte ho dazr a zvolte typ úložiště webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: uživatelské jméno (dzw_…). Password: zvolte vlastní zadání a vložte heslo.
3. Bearer token nechte prázdný a uložte. Ověřte pomocí rclone lsd dazr: a pak zálohujte.

# ~/.config/rclone/rclone.conf (rclone obscure <password> gives the pass value)
[dazr]
type = webdav
url = https://files.dazr.eu/dav/
vendor = other
user = dzw_0123456789abcdef0123
pass = <obscured password>

rclone lsd dazr:
rclone sync dazr: /backup/dazr --transfers 4

rclone porovnává velikost a čas změny. Použijte copy místo sync, aby v záloze zůstaly soubory smazané v Dazr Files.

Synology Cloud Sync

1. Otevřete na NAS Cloud Sync, přidejte poskytovatele cloudu a zvolte WebDAV.
2. Adresa serveru: https://files.dazr.eu/dav/. Uživatelské jméno a heslo: přihlášení WebDAV od administrátora.
3. Zvolte místní složku, vzdálenou složku / (nebo jednu složku) a směr synchronizace Download remote changes only.

Cloud Sync s WebDAV, směr synchronizace „Download remote changes only“. Hyper Backup zálohy na WebDAV zapisuje, ale číst z něj neumí.