All filesystem endpoints share one path:
/filesystem/{root}/{path inside the root}{root} is where the path starts. It is one of:
me: your own home directory. This needs an API key.- The ID of a file or directory, like
6m6r7854Ubzt491q4AJuCb. This is how shared files are opened, with or without an API key. The ID of a shared directory is the last part of its link on the website. Your own files and directories can be opened by their ID too.
The rest is a normal path with slashes. Names in the path have to be URL
encoded, so a space is %20. Some examples:
/filesystem/me
/filesystem/me/documents/report.pdf
/filesystem/6m6r7854Ubzt491q4AJuCb
/filesystem/6m6r7854Ubzt491q4AJuCb/photos/2026/beach.jpgAn API key needs the filesystem_read permission to read and
filesystem_write to change things. A key which is limited to certain
directories can only use the IDs of those directories as root, not me. See
API keys.
The limits of the filesystem, like the maximum length of a name, are in the filesystem guide.
The node object#
Files and directories are called nodes. Most endpoints return them in this form:
{
"id": "MoDmdQKTq3P1FMPoRcoATw",
"type": "file",
"path": "/me/documents/report.pdf",
"name": "report.pdf",
"created": "2026-09-14T09:21:07.512Z",
"modified": "2026-09-14T09:21:07.512Z",
"mode_string": "-rw-r--r--",
"mode_octal": "644",
"created_by": "wim",
"recursive_size": 0,
"recursive_children": 0,
"file_size": 482113,
"file_type": "application/pdf",
"sha256_sum": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
}| Field | Meaning |
|---|---|
id |
The ID of the node. It stays the same when the node is renamed or moved |
type |
file or dir |
path |
The full path, starting with the root the request used: /me/... or /{id}/... |
name |
The name of the node |
created, modified |
Times of creation and of the last change to the contents |
mode_string, mode_octal |
The Unix file mode. Nova keeps it for programs like rclone, but does not use it for access control |
created_by |
User name of the user who created the node |
recursive_size |
For a directory: the size of everything in it, in bytes. Counted in the background, so it can be behind |
recursive_children |
For a directory: the number of files and directories in it, at all levels. Counted in the background too |
file_size |
Size of the file in bytes |
file_type |
MIME type of the file. Nova detects it when the file is uploaded |
sha256_sum |
SHA-256 hash of the file in hex |
These fields are only there when they have a value:
| Field | Meaning |
|---|---|
properties |
Object with the branding options of the node, see update |
logging_enabled_at |
When the change log was turned on, see change log |
abuse_type |
The node was blocked for breaking the content policy, this is the reason |
link_permissions |
What people with the link can do. Only visible to the owner |
user_permissions |
What other users can do, by user name. Only visible to the owner |
password_permissions |
What the holders of a password can do, by password. Only visible to the owner |
How the three permission fields work is explained under Sharing.
GET /filesystem/{path}#
What this returns depends on the node and on the query string:
- A file without a query string is downloaded.
- A directory without a query string gives its information and
contents.
?statgives the same for a file. - The other options are listed below. Each of them is a parameter without a
value in the query string, like
?thumbnail.
Permission: filesystem_read, if the request has a key. Shared files can be
read without a key.
Download a file#
curl -u ":$NOVA_KEY" -O https://nova.storage/api/filesystem/me/documents/report.pdfThe response is the file itself. Range requests work, so a download can be
continued where it stopped and a video can be played from any point. The
response has these headers:
| Header | Value |
|---|---|
Content-Type |
The file_type of the node |
ETag |
The SHA-256 hash of the file, in quotes |
Last-Modified |
The modified time of the node |
Content-Disposition |
inline with the name of the file. With ?attach in the URL it is attachment, which makes a browser save the file instead of showing it |
Downloads count towards a transfer limit. The owner of the file pays for the
download as long as they have transfer left. After that it comes from the
account which makes the request. If neither has transfer left the error is
out_of_transfer.
When a file is embedded in a page on another website, the browser tells us so.
Such a request gets embed_not_allowed if the owner has a list of embed
domains and the other website is not on it.
Node information and directory listing#
GET /filesystem/{path}?stat
Returns the node, every directory above it up to the root, and what is in it if it is a directory.
curl -u ":$NOVA_KEY" "https://nova.storage/api/filesystem/me/documents?stat"{
"path": [
{"id": "9XqkCw4HvAWQH7vGoMvQyq", "type": "dir", "path": "/me", "name": "wim"},
{"id": "kPH3q7JP4Syg6Fi5HSemA", "type": "dir", "path": "/me/documents", "name": "documents"}
],
"base_index": 1,
"children": [
{"id": "MoDmdQKTq3P1FMPoRcoATw", "type": "file", "path": "/me/documents/report.pdf", "name": "report.pdf"}
],
"permissions": {"owner": true, "read": true, "write": true, "delete": true},
"context": {"premium_transfer": true, "can_share": true}
}(The nodes are shortened here, they have all the fields of the node object.)
| Field | Meaning |
|---|---|
path |
The nodes from the root to the node which was asked for, in that order |
base_index |
The position in path of the node which was asked for. It is the last one |
children |
The contents of the directory. Empty for a file. All of them come in one response, there are no pages |
permissions |
What this request is allowed to do with the node |
context.premium_transfer |
Whether downloads are paid for from the transfer of an account |
context.can_share |
Whether the plan of the owner allows sharing |
Thumbnail#
GET /filesystem/{path}?thumbnail
Returns a PNG image. For images and videos it is a small version of the file. For other files and for directories it is an icon which fits the type.
| Parameter | Required | Value |
|---|---|---|
width |
no | 16 to 256, in steps of 16. The default is 256 |
height |
no | The same. width and height only count when both are sent |
A size which is not allowed gives invalid_thumbnail_size.
Search#
GET /filesystem/{path}?search={term}
Searches the names of everything in a directory, at all levels.
| Parameter | Required | Value |
|---|---|---|
search |
yes | What to look for, 2 to 100 characters |
limit |
no | Maximum number of results, 1 to 1000. Default 10 |
- A name matches when the term is somewhere in it.
- The search ignores upper and lower case, unless the term has an upper case letter in it. Then the case has to match.
- A term with a
/in it is compared to the whole path instead of the name.
The response is a list of paths:
["/me/documents/report.pdf", "/me/archive/2025/report-final.pdf"]Errors: search_not_a_directory, search_term_too_short,
search_term_too_long, search_index_too_large.
Download a directory as zip#
GET /filesystem/{path}?bulk_download
Returns a zip file with everything in the directory. The zip is made while it
is sent, so the response has no Content-Length and the download can’t be
continued when it breaks. When a file can’t be read after the zip has started,
the server breaks the connection off instead of finishing the zip, so your HTTP
client reports an incomplete response.
To download only a part of the directory, add an include parameter for every
file or directory you want. The value is the path inside the directory:
GET /filesystem/me/documents?bulk_download&include=report.pdf&include=archive/2025
The names in the zip are the paths inside the directory, without a / in
front.
Trash#
GET /filesystem/{path}?trash
Lists what is in the trash of a directory. The trash of your account is the one
of the home directory: GET /filesystem/me?trash. Things get there with
DELETE ?trash.
[
{
"node": {"id": "MoDmdQKTq3P1FMPoRcoATw", "type": "file", "path": "/me/.Trash/files/report.pdf", "name": "report.pdf"},
"original_path": "/documents/report.pdf",
"deletion_date": "2026-10-02T15:04:05Z"
}
]original_path is where the node was, as a path inside the root. To put a
node back, rename it from node.path to the root followed by
original_path.
The trash is a directory called .Trash which follows the trash specification
of freedesktop.org. That is the one Linux file managers use, so they can show
and empty the trash of a mounted Nova filesystem.
Change log#
GET /filesystem/{path}?change_log&start={time}&end={time}
Returns what changed in a directory between two times. The time span can be 30 days at most, and log entries are kept for a year.
The log of your home directory is always kept. For any other directory logging
has to be turned on first, with logging_enabled in an
update. It stays on for 24 hours, and asking for the log
keeps it on.
[
{
"time": "2026-10-02T15:04:05.123Z",
"path": "/documents/report.pdf",
"path_new": "/archive/report.pdf",
"action": "move",
"type": "file"
}
]action is update, move or delete. path_new is only filled in for a
move. The paths start at the directory the log belongs to.
Errors: node_is_not_a_directory, log_timespan_too_long.
Download statistics#
GET /filesystem/{path}?download_stats
Only for files. Returns how often the file was downloaded, and how many bytes were sent for it:
{"downloads": 1204, "egress": 580463782}When the request is a WebSocket upgrade, the connection stays open and gets a new message in this format whenever the numbers change.
GET /filesystem/{path}?timeseries&start={time}&end={time}&interval={minutes}
Only for files. Returns the same two numbers over time. interval is the
length of one step in minutes, 1 to 1440.
{
"downloads": {
"timestamps": ["2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z"],
"amounts": [311, 204]
},
"egress": {
"timestamps": ["2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z"],
"amounts": [150032871, 98377102]
}
}Look inside an archive#
GET /filesystem/{path}?zip_info
Lists the contents of an archive without downloading it. It works for zip, 7z,
tar, tar.gz and tar.xz files. The response is a tree. Every entry has the size
it has when it is unpacked, and a directory has its entries in children:
{
"size": 73411,
"children": {
"photos": {
"size": 73200,
"children": {
"beach.jpg": {"size": 73200}
}
},
"readme.txt": {"size": 211}
},
"properties": ["read_individual_files"]
}properties can have these values in it:
read_individual_files: files can be taken out of this archive withzip_file, see below. Only zip files have this.truncated: the archive took too long to read and the list is not complete.
GET /filesystem/{path}?zip_file={path inside the archive}
Downloads one file out of a zip or 7z archive. For a zip file the path can also be a directory in the archive. The response is then a new zip with only that directory in it.
Errors: not_a_zip, invalid_zip_file, unsupported_zip_compression.
Look inside a torrent#
GET /filesystem/{path}?torrent_info
Returns what is in a torrent file. files is a tree like the one of an
archive.
{
"trackers": ["udp://tracker.example.com:1337/announce"],
"comment": "",
"created_by": "qBittorrent v5.0.0",
"created_at": "2026-09-14T09:21:07Z",
"info_hash": "2c6b6858d61da9543d4231a71db4b1c9264b0685",
"files": {
"size": 4071903232,
"children": {
"debian.iso": {"size": 4071903232}
}
}
}Errors: not_a_torrent, torrent_too_large (the limit is 16 MiB),
torrent_parse_failed.
Render markdown#
GET /filesystem/{path}?render_markdown
Returns a markdown or plain text file as HTML. The HTML is cleaned, so it is
safe to put in a page. Files over 2 MiB give file_too_large, other types of
file give not_a_markdown_file.
PUT /filesystem/{path}#
Uploads a file. The body of the request is the contents of the file, as they are. If there is a file at the path already, it is replaced.
Permission: filesystem_write.
curl -u ":$NOVA_KEY" -T report.pdf \
"https://nova.storage/api/filesystem/me/documents/report.pdf?make_parents=true"Parameters go in the query string:
| Parameter | Required | Value |
|---|---|---|
make_parents |
no | true creates the directories in the path which are not there yet. Without it a missing directory gives path_not_found |
The parameters of the update action work here too. A backup
tool can use created, modified and mode to keep the times and the mode of
the file it uploads. A new file gets the mode 644 when the request has none.
The response is the node of the new file.
Things to know:
- A file can be 100 GB at most.
- The body must not be a form. A
multipart/form-databody givesinvalid_content_type, and with the content typeapplication/x-www-form-urlencodedthe file ends up empty. With curl, use-Tor--upload-file, not-dor-F. - An upload can’t be continued and a file can’t be added to. Every upload sends the whole file.
- When the upload breaks off nothing is saved, and a file which was already at the path stays as it was.
Errors: user_out_of_space, account_banned, node_is_a_directory.
POST /filesystem/{path}#
Does something with the node at the path. What it does is in the action
parameter.
Permission: filesystem_write.
action: mkdir#
Creates a directory at the path. The directory above it has to exist.
curl -u ":$NOVA_KEY" -d action=mkdir \
https://nova.storage/api/filesystem/me/documents/2026| Parameter | Required | Value |
|---|---|---|
mode |
no | The mode of the new directory in octal, like 755. The default is 700 |
The response has status 201 and the value created. If there is something at
the path already the error is node_already_exists.
action: mkdirall#
The same as mkdir, but it also creates the directories above it which are
not there yet. It is not an error if the directory exists already.
action: rename#
Renames or moves the node at the path.
curl -u ":$NOVA_KEY" -d action=rename \
--data-urlencode "target=/me/archive/report 2026.pdf" \
https://nova.storage/api/filesystem/me/documents/report.pdf| Parameter | Required | Value |
|---|---|---|
target |
yes | The new path, with the root in front. The root has to be the same as the one in the URL: a node can’t be moved to another root |
make_parents |
no | true creates the directories in the target which are not there yet |
The response is the node at its new path. The ID of the node stays the same.
Errors: node_already_exists when the target is taken, circular_dependency
when a directory is moved into itself, path_not_found when the target has
another root, cannot_modify_root_dir.
The parameters of the update action below work with a rename too.
action: update#
Changes the properties of a node. Only the parameters which are sent are changed. The response is the updated node.
| Parameter | Value |
|---|---|
created |
New time of creation |
modified |
New time of the last change |
mode |
The Unix file mode in octal, like 644. This is the format of mode_octal |
logging_enabled |
true or false, turns the change log of a directory on or off |
link_permissions |
JSON, see Sharing |
user_permissions |
JSON, see Sharing |
password_permissions |
JSON, see Sharing |
The branding options change how the download page of a shared node looks. An empty value removes the option.
| Parameter | Value |
|---|---|
branding_enabled |
true or false |
brand_input_color, brand_accent_color, brand_green_color, brand_red_color, brand_yellow_color, brand_blue_color, brand_background_color, brand_body_color, brand_card_color |
A colour, like #3a8f6b |
brand_header_image |
The ID of an image file in your filesystem |
brand_background_image |
The ID of an image file in your filesystem |
brand_header_link |
The address the header image links to, up to 255 characters |
The sharing and branding parameters only work for the owner of the node. When somebody else sends them they are ignored, without an error.
Sharing#
A node is shared by giving other people permissions on it. There are three ways, and each is a parameter of the update action. A permission is an object with three booleans:
{"read": true, "write": false, "delete": false}The permissions count for the node and everything in it, and only when the
node is opened by its ID: /filesystem/{id of the shared node}/.... Sharing
needs a plan which allows it. Without one the error is sharing_not_allowed,
and when the plan of the owner stops allowing it, visitors of the shared nodes
get permission_denied.
link_permissions is for everybody who has the ID. This is what makes a
public link.
curl -u ":$NOVA_KEY" -d action=update \
-d 'link_permissions={"read": true, "write": false, "delete": false}' \
https://nova.storage/api/filesystem/me/documentswrite only works for visitors who are logged in, because everything in the
filesystem needs to have a user who created it.
user_permissions is for other users of Nova. It is an object with user
names as keys. The object replaces the list which was there, so send all users
every time. A name which does not exist gives user_not_found.
{
"alice": {"read": true, "write": true, "delete": false},
"bob": {"read": true, "write": false, "delete": false}
}password_permissions is for everybody who has one of the passwords. The
keys are the passwords, of 8 to 50 characters. Each one can have a label of
up to 100 characters to remember what it is for. This object replaces the list
which was there too.
{
"nB7q2LwX9cRt4VzK": {"read": true, "write": true, "delete": false, "label": "Backup of the NAS"}
}Send the password in the password parameter of the URL. It also works in a
cookie called nova_fs_password, URL encoded, which is what the website uses.
What a password holder writes without being logged in is created by the owner
of the directory. S3 clients use the password as their secret key, see S3 in
the filesystem guide.
curl "https://nova.storage/api/filesystem/{id}?stat&password=nB7q2LwX9cRt4VzK"When a request is refused and the directory has passwords, the error is
password_required instead of permission_denied, unless the request had a
valid password already.
The user and password lists can have 100 entries each.
The owner of a node sees the three fields in the node object.
Entries of user_permissions and password_permissions have a last_used
time in them once they were used.
When more than one applies to a request, the user permissions go before the password and the password before the link. The owner of the root, and the user who created a node, can always do everything with it.
DELETE /filesystem/{path}#
Deletes a file or an empty directory. A directory with something in it gives
directory_not_empty.
Permission: filesystem_write. With sharing, the delete permission.
curl -u ":$NOVA_KEY" -X DELETE \
"https://nova.storage/api/filesystem/me/documents/old?recursive"The query string can have one of these in it:
| Parameter | What it does |
|---|---|
recursive |
Deletes a directory with everything in it |
trash |
Moves the node to the trash instead of deleting it. A directory does not have to be empty. A node which is in the trash already is deleted for good |
empty_trash |
Deletes everything in the trash of the directory at the path. The directory itself is not touched |
Without trash a delete can’t be undone.
The root itself can’t be deleted, that gives cannot_modify_root_dir.
Errors#
| Status | value |
Meaning |
|---|---|---|
| 400 | permission_denied |
You are not allowed to do this with this path, or the API key is not allowed to use it |
| 403 | password_required |
You are not allowed to do this, but one of the passwords of the directory may allow it |
| 400 | node_already_exists |
There is a file or directory with this name already |
| 400 | directory_not_empty |
The directory has something in it, use recursive |
| 400 | node_is_a_directory |
This can only be done with a file |
| 400 | node_is_not_a_directory |
This can only be done with a directory |
| 400 | name_too_long |
A name is longer than 255 bytes |
| 400 | path_too_long |
The path is longer than 4095 bytes |
| 400 | too_many_nested_levels |
The path has more than 64 directories in it |
| 400 | too_many_children |
The directory is full, it has 1000000 files and directories in it |
| 400 | directory_overflow |
The directory was changed so often that it can’t be listed for now. This goes away by itself in about a day. The files in it can still be opened |
| 400 | circular_dependency |
A directory can’t be moved into itself |
| 400 | cannot_modify_root_dir |
The root can’t be renamed, deleted or created |
| 400 | invalid_action |
action is not one of the actions |
| 400 | sharing_not_allowed |
The plan of the account does not allow sharing |
| 400 | user_out_of_space |
The storage of the account is full |
| 400 | out_of_transfer |
There is no transfer left to pay for this download |
| 400 | invalid_content_type |
An upload was sent as a form |
| 400 | error_reading_input |
The upload broke off |
| 403 | account_banned |
The account was banned for breaking the content policy |
| 403 | embed_not_allowed |
The file can’t be embedded on this website |
| 404 | not_found |
There is no node with the ID which is used as root |
| 404 | path_not_found |
There is nothing at this path |
| 413 | file_too_large |
The file is too large for this |
| 451 | unavailable_for_legal_reasons |
The node was blocked after an abuse report. extra has abuse_type and abuse_report_time |