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. If you use claude code, you can set it up like this:

~/$ claude mcp add filestash npx mcp-remote https://demo.filestash.app/sse
Added stdio MCP server filestash with command: npx mcp-remote https://demo.filestash.app/sse to local config

Next time you open up claude, it will open up a browser window to the authentication page and you should see something like this: mcp screenshot

> /mcp
╭───────────────────────────────────────────────────────────╮
│ Manage MCP servers                                        │
│                                                           │
│ ❯ 1. filestash ✔ connected · Enter to view details        │
╰───────────────────────────────────────────────────────────╯
     Esc to exit

 > can you list the files at the root of the remote storage?
● I'll help you list the files at the root of the remote
storage. Let me use the MCP filestash tool to do this.

● filestash:ls (MCP)(path: "/")
⎿  [DIR] Pictures
    [DIR] Music
    [DIR] Videos
    … +2 lines (ctrl+r to expand)

● The root directory contains:
  - Pictures/ (directory)
  - Music/ (directory)
  - Videos/ (directory)
  - README.org (file)
  - Documents/ (directory)