These endpoints create an account, log in to it and manage its settings. The endpoints for API keys are on their own page, and so are the ones for billing.
POST /user/register#
Creates an account. No API key is needed.
| Parameter | Required | Value |
|---|---|---|
username |
yes | 1 to 30 characters. No /, no @, no control characters, and no space at the start or the end |
email |
yes | An e-mail address, up to 100 characters |
password |
yes | 5 to 50 characters |
The request needs an Origin header with the address of the Nova website in
it, like a browser sends from our registration page:
curl -H "Origin: https://nova.storage" \
-d username=alice -d email=alice@example.com -d password=correct-horse \
https://nova.storage/api/user/registerThe response has status 201 and the value created. Nova then sends an e-mail
with a link to confirm the address. The link is valid for 30 minutes and logs
the user in.
An IP address can register 10 accounts per day.
| Status | value |
Meaning |
|---|---|---|
| 400 | username_already_registered |
The user name is taken |
| 400 | email_address_already_registered |
There is an account with this address |
| 400 | request_origin_invalid |
The Origin header is missing or is not ours |
| 429 | ip_rate_limit_reached |
Too many registrations from this IP address |
POST /user/login#
Logs in and returns a new API key with all permissions. No API key is needed.
This is how the website logs a user in. A program which only needs access to one account does not have to log in: create a key on the API keys page and use that.
Like registration, the request needs an Origin header with the address of the
Nova website. An IP address can try to log in 10 times per hour.
There are two ways to log in.
With a password:
| Parameter | Required | Value |
|---|---|---|
username |
yes | The user name or the e-mail address of the account |
password |
yes | The password |
totp |
no | The six digit code of the authenticator app, for accounts with two-factor authentication |
app_name |
no | A name for the key, up to 100 characters. It is shown on the API keys page |
curl -H "Origin: https://nova.storage" \
-d username=alice -d password=correct-horse -d app_name="My script" \
https://nova.storage/api/user/loginWith a link by e-mail: send the e-mail address of the account as
username, without a password. The response has status 202 and the value
login_link_sent. The user gets an e-mail with a link to the website, which is
valid for 30 minutes. The link has two parameters in it, and the login is
finished by sending those:
| Parameter | Required | Value |
|---|---|---|
link_login_user_id |
yes | From the link |
link_login_id |
yes | From the link |
totp, app_name |
no | As above |
When the first request has a redirect parameter, a path on the website of up
to 2000 characters, it is put in the link too. The website sends the user
there after the login.
A login which works has status 201. The response is the new key, in the format
which is described under API keys. auth_key
is the key itself:
{
"auth_key": "c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22",
"creation_ip_address": "203.0.113.7",
"user_agent": "curl/8.9.1",
"app_name": "My script",
"creation_time": "2026-10-02T15:04:05.123Z",
"last_used_time": "2026-10-02T15:04:05.123Z",
"filesystem_read": true,
"filesystem_write": true,
"filesystem_dirs": []
}(Some fields are left out here.) The response also sets the key as
the nova_auth_key cookie, which is what the website uses.
Logging in cancels the deletion of an account, see DELETE /user.
| Status | value |
Meaning |
|---|---|---|
| 202 | login_link_sent |
Not an error: a link was sent by e-mail |
| 400 | password_incorrect |
The password is wrong |
| 400 | otp_required |
The account has two-factor authentication, send totp |
| 400 | otp_incorrect |
The code in totp is wrong |
| 400 | no_login_method_available |
There was no password, and username is not the e-mail address of the account |
| 400 | login_link_already_sent |
A link was sent less than 30 minutes ago and was not used yet |
| 400 | invalid_login_link |
The link is wrong, was used or has expired |
| 400 | request_origin_invalid |
The Origin header is missing or is not ours |
| 404 | user_not_found |
There is no account with this name or address |
| 429 | ip_rate_limit_reached |
Too many logins from this IP address |
GET /user#
Returns the account the API key belongs to.
Permission: account_read.
curl -u ":$NOVA_KEY" https://nova.storage/api/user{
"id": "5b1a3a52-27f8-4e7c-8a0f-1d0f1c3e9a55",
"username": "alice",
"email": "alice@example.com",
"email_verified": true,
"otp_enabled": false,
"subscription": {
"id": "sagittarius",
"name": "Sagittarius",
"type": "subscription",
"monthly_fee": 16000000,
"min_months": 1,
"file_size_limit": 100000000000,
"storage_limit": 8000000000000,
"price_per_tb_storage": 4000000,
"price_per_tb_bandwidth": 1000000,
"monthly_transfer_cap": 16000000000000,
"file_sharing": true
},
"storage_space_used": 71244835712,
"filesystem_storage_used": 71244835712,
"filesystem_node_count": 18211,
"is_admin": false,
"balance_micro_eur": 24500000,
"subscription_months": 1,
"subscription_period_end": "2026-10-28T00:00:00Z",
"monthly_transfer_cap": 0,
"monthly_transfer_used": 9120338177,
"embed_domains": "",
"affiliate_user_name": "",
"checkout_country": "NLD",
"checkout_name": "",
"checkout_provider": "",
"usage_based_billing": false
}| Field | Meaning |
|---|---|
id |
The ID of the account |
username, email |
User name and e-mail address |
email_verified |
Whether the user confirmed the e-mail address |
otp_enabled |
Whether two-factor authentication is on |
subscription |
The plan of the account, see GET /misc/subscriptions for the fields |
filesystem_storage_used |
Storage in use, in bytes. storage_space_used is the same number |
filesystem_node_count |
Number of files and directories in the account |
is_admin |
Whether this is an account of Nova staff |
balance_micro_eur |
The credit on the account |
subscription_months |
Length of the subscription period in months |
subscription_period_end |
When the current subscription period ends |
monthly_transfer_cap |
The transfer limit the user set for themselves, in bytes. 0 is no limit |
monthly_transfer_used |
Transfer used in the last 30 days, in bytes |
embed_domains |
The websites which can embed files of this account, with spaces in between. Empty is all of them |
affiliate_user_name |
The user who gets the affiliate reward for this account |
checkout_country, checkout_name, checkout_provider |
What the user filled in at their last payment, to fill the form in for them next time |
usage_based_billing |
Whether usage above the limits of the plan is billed, instead of blocked. See charges |
PUT /user#
Changes the settings of the account. Only the parameters which are sent are changed.
Permission: account_write for the account settings and billing_write for
the billing settings. A request needs the permission of every parameter in it.
Account settings:
| Parameter | Value |
|---|---|
username |
A new user name, see register for the rules |
password_new |
A new password, 5 to 50 characters |
email |
A new e-mail address. An empty value removes the address |
embed_domains |
Domain names with spaces in between, up to 1024 characters. Only these websites can embed files of the account. An empty value removes the limit |
affiliate_user_name |
The user name of the account which gets the affiliate reward. An empty value removes it |
Billing settings:
| Parameter | Value |
|---|---|
subscription |
The id of a plan, see changing the plan |
subscription_months |
The subscription period: 1, 6 or 12 |
usage_based_billing |
true or false |
transfer_cap |
A transfer limit per 30 days in bytes, to keep downloads of shared files from using all transfer. 0 removes it. It can’t be higher than the transfer of the plan, unless usage based billing is on |
checkout_country |
Country code of three letters |
checkout_name |
Name for payments, up to 100 characters |
checkout_provider |
The payment method the user chose last |
curl -u ":$NOVA_KEY" -X PUT \
-d "embed_domains=example.com www.example.com" \
https://nova.storage/api/userThe response has the value ok.
A new e-mail address is not saved right away. Nova sends a link to the new
address and saves it when the link is opened. The response then has status 202
and the value login_link_sent, and other settings in the same request are
not saved. So change the e-mail address in a request of its own. Like a
login, that request needs an Origin header with the address of the Nova
website, because the link in the e-mail goes there.
| Status | value |
Meaning |
|---|---|---|
| 400 | username_already_registered |
The user name is taken |
| 400 | email_address_already_registered |
There is an account with this address |
| 400 | invalid_domain_name |
A name in embed_domains has no period in it |
| 400 | usage_above_plan_limits |
Usage based billing can’t be turned off while the account is above the limits of its plan |
| 400 | login_link_already_sent |
A link was sent less than 30 minutes ago and was not used yet |
| 400 | request_origin_invalid |
The e-mail address was changed without an Origin header of ours |
| 404 | user_not_found |
The user in affiliate_user_name does not exist |
The errors of a plan change are on the billing page.
DELETE /user#
Deletes the account.
Permission: account_write.
All API keys of the account are deleted right away, the one of this request included. The account and its files are deleted seven days later. Until then the user can log in, which cancels the deletion. If the account has an e-mail address, Nova sends a message to it which explains this.
The response has the value ok.
GET /user/time_series/{statistic}#
Returns how much the files of the account were downloaded over time.
Permission: account_read.
{statistic} is downloads for the number of downloads, or egress for the
number of bytes.
| Parameter | Required | Value |
|---|---|---|
start |
yes | Start time |
end |
yes | End time |
interval |
yes | Length of one step in minutes, 1 to 1440 |
curl -u ":$NOVA_KEY" \
"https://nova.storage/api/user/time_series/egress?start=2026-10-01T00:00:00Z&end=2026-10-02T00:00:00Z&interval=1440"{
"timestamps": ["2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z"],
"amounts": [150032871, 98377102]
}The two lists have the same length. amounts[i] is the total of the step which
starts at timestamps[i].
GET /user/activity/{month}#
Returns what happened to the files of the account in a month. {month} has the
format 2026-10. The newest event comes first.
Permission: account_read.
[
{
"time": "2026-10-02T15:04:05.123Z",
"event": "filesystem_node_blocked",
"file_id": "MoDmdQKTq3P1FMPoRcoATw",
"file_name": "report.pdf",
"file_removal_reason": "copyright"
}
]event |
Meaning |
|---|---|
filesystem_node_blocked |
A file or directory was blocked after an abuse report. The reason is in file_removal_reason |
filesystem_node_lost |
A file was lost on our side |
GET /user/bans#
Returns the bans of the account. An account gets banned when it shares files which break the content policy. A banned account can’t upload.
Permission: account_read.
[
{
"ban_time": "2026-09-20T11:30:00Z",
"expire_time": "2026-10-20T11:30:00Z",
"reason": "copyright",
"file_link": "/d/6m6r7854Ubzt491q4AJuCb",
"file_name": "report.pdf"
}
]file_link is the path on the website of the file the ban was given for.
POST /user/totp#
Manages two-factor authentication with an authenticator app (TOTP).
Permission: account_write.
What it does is in the action parameter. Turning it on takes two requests:
action=generate makes a new secret. Nothing is saved yet.
{
"secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
"uri": "otpauth://totp/Nova.storage:alice?algorithm=SHA1&digits=6&issuer=Nova.storage&period=30&secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"
}Show uri to the user as a QR code, which they scan with their app. GET
/misc/qr can make the image.
action=verify checks that the app of the user works, and turns two-factor
authentication on.
| Parameter | Required | Value |
|---|---|---|
secret |
yes | The secret from generate |
otp |
yes | The six digit code the app shows |
The response has the value ok, or the error otp_incorrect when the code is
wrong.
action=delete turns two-factor authentication off.