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.jpg

An 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. ?stat gives 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.pdf

The 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.

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 with zip_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-data body gives invalid_content_type, and with the content type application/x-www-form-urlencoded the file ends up empty. With curl, use -T or --upload-file, not -d or -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/documents

write 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