Nova has a REST API which can do everything the website can do, because the website uses it too. The API lives at:
https://nova.storage/apiEvery path in this documentation comes after that address, so GET /user is a
GET request to https://nova.storage/api/user.
The API is split into these parts:
- Filesystem: upload, download, list, move, delete and share files
- Account: registration, login, account settings and statistics
- API keys: create and delete API keys, and what the permissions of a key mean
- OAuth login for apps: let users log in to your app without giving it their password
- Billing: subscription plans, invoices and transactions
- Miscellaneous: server status, speed test and QR codes
If you only want to manage your files, you probably don’t need the API at all. Rclone, FTP and S3 are described in the filesystem guide.
Authentication#
Requests are authenticated with an API key. You can create one on the API keys page. Send the key as the password of HTTP Basic authentication. The user name is ignored and can be left empty:
curl -u ":$NOVA_KEY" https://nova.storage/api/userWithout a tool which does this for you, the header looks like this, with
: and the key encoded as base64:
Authorization: Basic OmM3ZDhjYTVkLTNiMGUtNGIwYS05YTVlLTBmNmYwYzdhMWIyMg==A key can also be sent as a Bearer token. That is how apps which log their users in with OAuth send it:
Authorization: Bearer c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22A key can be limited in what it is allowed to do, and in which directories it works. See API keys for the permissions. Each endpoint in this documentation lists the permission it needs.
A key expires when it has not been used for 30 days. Every request renews it.
The website itself sends its key in a cookie called nova_auth_key. Other
clients should use the header.
| Status | value |
Meaning |
|---|---|---|
| 401 | authentication_required |
The endpoint needs a key and the request had none |
| 401 | authentication_failed |
The key does not exist, was deleted or has expired |
| 403 | key_permission_denied |
The key does not have the permission which is needed |
Requests#
Parameters are sent in the query string of the URL, or in the body as a form.
Both application/x-www-form-urlencoded and multipart/form-data work. The
API does not read JSON bodies. Where a parameter holds a list or an object, its
value is a string of JSON.
- Booleans are
trueorfalse. - Times are in RFC 3339 format, like
2026-10-02T15:04:05Z. - Sizes are in bytes.
- Amounts of money are in micro-euro:
1000000is €1. - If a parameter is sent more than once, only the first value counts.
- The body of a request can be 5 MB at most. File uploads are the exception.
Every endpoint which answers to GET also answers to HEAD.
The API does not send CORS headers. A web page on another site can’t call it from the browser.
Responses#
Responses are JSON, unless the endpoint returns a file. An endpoint which has nothing to return answers with status 200 or 201 and one of these:
{"success": true, "value": "ok", "message": "The requested action was successfully performed"}{"success": true, "value": "created", "message": "The submitted resource was created"}Responses are compressed when the Accept-Encoding header of the request has
gzip or zstd in it.
Errors#
An error has an HTTP status of 400 or higher and this body:
{
"success": false,
"value": "path_not_found",
"message": "No file or directory found with this path"
}value is the name of the error. It does not change, so this is the field to
check in your code. message is meant for people and can change.
Some errors have an extra object with details, like the name of the parameter
which was wrong:
{
"success": false,
"value": "string_out_of_range",
"message": "A string parameter you passed was either too short or too long",
"extra": {"field": "password", "min_len": 5, "max_len": 50, "len": 3}
}When the parameters of a request are checked, every problem is reported at
once. The error is then multiple_errors, with the list in errors. This is
also what you get when only one parameter was wrong:
{
"success": false,
"value": "multiple_errors",
"message": "This API endpoint can return multiple errors which need to be checked individually. See the errors array",
"errors": [
{
"success": false,
"value": "missing_field",
"message": "A required field was not sent with this request. See extra for more information",
"extra": {"field": "text"}
}
]
}These errors can come from any endpoint. The errors which belong to one part of the API are listed on the page of that part.
| Status | value |
Meaning |
|---|---|---|
| 400 | multiple_errors |
One or more parameters are wrong, see errors |
| 400 | missing_field |
A required parameter is missing |
| 400 | invalid_email_address |
A parameter is not an e-mail address |
| 400 | field_contains_illegal_character |
A parameter has a character in it which is not allowed |
| 404 | not_found |
The thing which was asked for does not exist |
| 422 | string_out_of_range |
A parameter is too short or too long |
| 422 | integer_parse_failed |
A parameter is not a number |
| 422 | integer_out_of_range |
A number is too low or too high |
| 422 | bool_parse_failed |
A parameter is not true or false |
| 422 | time_parse_failed |
A time is not in RFC 3339 format |
| 422 | enum_parse_failed |
A parameter is not one of the allowed values, which are in extra.allowed_values |
| 422 | uuid_parse_failed |
A parameter is not a valid ID |
| 422 | json_parse_failed |
A parameter is not valid JSON |
| 422 | utf8_string_parse_failed |
A parameter or the path is not valid UTF-8 |
| 422 | too_many_map_entries |
A list or object has too many entries, the limit is in extra.max |
| 429 | ip_rate_limit_reached |
Too many requests from this IP address, see below |
| 500 | internal |
Something went wrong on our side |
| 503 | temporarily_unavailable |
The server could not answer in time. Nothing is wrong with the request, try it again |
Rate limits#
An IP address can make 6000 requests per minute. Above that the API answers
with status 429 and the error ip_rate_limit_reached.
Logging in and registering have their own limits, which are on the account page.