API & Gateways

Filestash lets you interact with any kind of remote storages via its API. Some of its plugins expose those same storages through Gateways that speak protocols like SFTP, MCP and S3.

API

To use the builtin API, you will need to either start from an access token or the ID of a shared link. To generate a token:

~/$ curl -d '{"type":"tmp","userID":"test"}' https://demo.filestash.app/api/session
{
    "status": "ok",
    "result": {
        "home": "/",
        "is_authenticated": true,
        "backendID": "kcXbLbQdv3bGbHcQbKc7",
        "authorization": "OOK4PKntipHivP0mhW2me9vVTJrGyCjqMceGbR4J1QSorke_RYf5aAid7k_nguHb4zfans_tUU5DuZaLexjHCL1ZeUXOIbr7_4A1slDbVo2znYyYQV_zArCE99wjr37VO-3RKYiS9buJTYWhK5I8ZQ=="
    }
}
 ~/$ # a trick to set the TOKEN env variable:
~/$ export TOKEN=`curl -s -d '{"type":"tmp","userID":"test"}' https://demo.filestash.app/api/session | jq -r '.result.authorization'`
~/$ echo $TOKEN
OOK4PKntipHivP1JS-QHxD3NMz42HRbRVjp1Ebkn9BhdW62dIWXdjt-sGQd-YHWlyEKWDRz3hsW9yLjMslTzZGRPmLwwFyU29jSxAgjGK35YIVdOs8Y_73UzbEwwje7k1XwfPkmtR324r8S7pyIDoQ==

There's an API endpoint for every possible file management operation you can think of:

~/$ # List files
~/$ curl -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/ls?path=/"
{
    "status": "ok",
    "results": [
        {
            "name": "file.txt",
            "type": "file",
            "size": 10778,
            "time": 1765261716167
        }
    ],
    "permissions": {}
}
 ~/$ # Upload a file
~/$ curl -d @file.txt -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/cat?path=/file.txt"
{
    "status": "ok"
}
 ~/$ # Download a file
~/$ curl -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/cat?path=/file.txt"
Lorem Ipsum
 ~/$ # Create a ZIP
~/$ curl -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/zip?path=/" > file.zip
~/$ unzip -l file.zip
 Archive:  test.zip
Length      Date    Time    Name
---------  ---------- -----   ----
    10778  1980-00-00 00:00   file.txt
---------                     -------
    10778                     1 file
 ~/$ # Rename Something
~/$ curl -X POST -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/mv?from=/file.txt&to=/foobar.txt"
{
    "status": "ok"
}
 ~/$ # Delete Something
~/$ curl -X POST -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/rm?path=/file.txt"
{
    "status": "ok"
}
 ~/$ # Create a Directory
~/$ curl -X POST -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/mkdir?path=/folder/"
{
    "status": "ok"
}
 ~/$ # Create an empty file
~/$ curl -X POST -H "Authorization: Bearer $TOKEN" "https://demo.filestash.app/api/files/touch?path=/file.txt"
{
    "status": "ok"
}

Gateways

The Filestash web client is not the only way to interact with your storage. Gateways act as translation hubs that convert a base protocol into any supported storage backend, whether it is S3, SFTP, FTP, SMB, ....

SFTP Gateway

We document this in detail in the SFTP Gateway guide. It lets you interact with Filestash from any SFTP client. My personal favorite is the CLI:

~/$ sftp -P 2222 test@127.0.0.1
test@127.0.0.1's password:
Connected to 127.0.0.1.
 sftp> ls
documents downloads
 sftp> documents/foobar/
documents/foobar/bin                     documents/foobar/boot
documents/foobar/core                    documents/foobar/dev
documents/foobar/dist                    documents/foobar/etc
...
 sftp>

MCP Gateway

The Model Context Protocol enables tool usage by an LLM. This is all documented in our MCP Gateway guide