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/register

The 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/login

With 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/user

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