Guida di Filarr

Receive files through the gate's API

Your software drops files through your gate, and Filarr files them by your rules. The gate drops, it never reads back.

In questa pagina
Sezioni della guida

Your invoicing software, a scanner or a script sends a file to your gate. The gate encrypts it for a permanent drop box, and your Filarr app then files it in the chosen folder, by your rules. The software learns "filed", never where.

Files through the API are offered from Pro (Pro, Teams, Enterprise). The number and volume of the month's deposits have a cap that depends on the plan: it shows in Settings → API access (Files received (month)). On the gate's side, Filarr Gate 0.3.1, the published version, can drop files.

How it works

  1. The software sends the file to the gate, with an app key allowed to drop files.
  2. The gate filters it (executables, size), computes its fingerprint, encrypts it for your drop box and drops it at Filarr.
  3. Filarr keeps the deposit sealed, unable to open it.
  4. One of your devices where Filarr is open (desktop or web) opens the deposit, checks the fingerprint, and files it by your placement rules.
  5. The gate learns that the file is filed, and when.

It is a slot: the gate drops, it can neither list, nor read back, nor delete what is filed. A stolen token lets someone drop, never read your files.

Who sees what

whoseesnever sees
Filarra sealed deposit, its size, the time, the access, the gate's IP addressthe name, the requested path, the tags, the fingerprint, the rule, the final folder
the gatethe file, which it encryptswhere it is filed, under which name, what your vault holds
your appeverything, to file it

Set it up

  1. On a database, click ··· then Open to an API… (Open a database to an API). Under What the access opens, tick Receive files. Choose the Drop box: one of yours, or a New box "API inbox" with its Target folder. That box also receives drops through its link, from the gateway.
  2. Create the access and give its token to the gate, as for a database.
  3. If needed, set the placement rules: Settings → API access → Received files, then Placement rules.
  4. In the gate, create an app key that can drop files: filarr-gate keys create --name ERP --files, or, in its admin interface, App keys › New key, ticking only "Deposit files".
  5. The software sends its files to the gate's address:
curl -H "Authorization: Bearer gk_live_..." \
  -F "file=@invoice-2291.pdf" \
  -F "path=Invoices/2026/10" \
  -F "tags=invoice,supplier" \
  https://gate.example.com/v1/files

The answer:

{
  "id": "dp_ZgD1ambaYz0Mgg54",
  "status": "deposited",
  "depositedAt": "2026-10-10T03:33:18.935Z",
  "seq": 2
}

path asks for a subfolder, which Filarr only accepts if you allowed it; tags can drive the rules.

Follow a deposit

GET /v1/files/<id> on the gate returns the deposit's state:

statewhat it means
depositedFilarr keeps it; no device has filed it yet
filedfiled (or recognised as a duplicate and left), with the time
rejectedyour app refused it: the fingerprint did not match, or the deposit was unreadable
expirednever filed during the box's retention period

The gate can also tell your software with a file.filed webhook when the file is filed.

What the gate refuses, before anything is sent

  • executables and scripts, by their extension (.exe, .msi, .bat, .cmd, .ps1, .sh, .js, .app, .jar, .dll and others) and by their first bytes, whatever the extension;
  • a file over 100 MiB (the gate's admin can lower this cap, never raise it);
  • any deposit when 200 files are already waiting to be filed in the box.

These refusals stay in the gate's log, on your side: they never left. Filarr could not analyse anything anyway, since the file reaches it encrypted. Nothing that is filed is ever run by Filarr.

When files wait

Only your app holds the folder's key: files are filed while Filarr is open on the desktop or the web, at the next pass (every 5 minutes). A device files the box as long as File automatically on this device is not switched off there (Settings → Integrations); File now does it on the spot.

At 200 waiting files, the gate refuses new deposits: waiting is not enough, open Filarr. The phone shows how many files are waiting, but does not file them.

Received files

Settings → API access → Received files shows, for each access that receives files: the month's files and what waits for a device, the drop box, the placement. Show the received files journal opens the detail: the time, the file, the app key, the result (filed, duplicate left, path refused, refused, waiting for a device, expired) and the folder it was filed in. This detail is sealed for your devices: only your app opens it.

Each filed file keeps its origin in its encrypted information: the access, the app key, the original name, the rule applied.

Learn more