N7 Storage

N7 Storage provides an on-demand API to upload files, allowing seamless access to those resources via your registered domain.

Prerequisite#

1. You must have an active account on Nitrogen.
2. Your target domain, where files will be uploaded and accessed, must be registered on Nitrogen.
3. A service account with Editor access must be configured. If you don’t have one, refer to this article to create API keys.

File and folder naming rules#

N7 Storage accepts a restricted set of characters in file and folder names. Uploads with any other name are rejected with a 400 error, whether they come from the API or the CLI.

• Every folder and file name must start with a letter or a digit.
• After the first character, only letters, digits, - and _ are allowed.
• A file name must contain exactly one dot, separating the name from its extension.
• Spaces and accented or non-English characters are not allowed.

The CLI can rename files for you automatically — see Fixing unsupported names .

CLI: Upload Bulk Files to N7 Storage#

storvia-cli scans a folder and uploads everything inside it, remembering what already succeeded so an interrupted run can be resumed.

Install#

• macOS, Linux and FreeBSD

  Copy

  curl --proto '=https' --tlsv1.2 -sSf https://storvia.n7.io/tools/install.sh | sh

• Windows (PowerShell)

  Copy

  irm https://storvia.n7.io/tools/install.ps1 | iex

The installer picks the right build for your machine, checks it against the published checksums, installs it to ~/.n7/bin (or %LOCALAPPDATA%\n7\bin on Windows), and tells you how to add that folder to your PATH.

Once installed, upgrade at any time with:

storvia-cli upgrade

To install somewhere else, pass a directory: curl ... | sh -s -- --dir /usr/local/bin

Download manually#

If you would rather not run a script, download the binary directly:

Checksums for every file are published at checksums.txt . On macOS and Linux, verify a download by comparing it against that list — replace apple/arm64 with the platform you downloaded:

curl -sSfL https://storvia.n7.io/tools/checksums.txt \
  | grep 'apple/arm64/storvia-cli' \
  | awk '{print $1"  storvia-cli"}' \
  | shasum -a 256 -c -

It prints storvia-cli: OK when the file is intact.

On macOS you may need to allow the downloaded binary to run, and on macOS or Linux mark it executable with chmod +x storvia-cli.

Sign in#

Store the service token for your domain once, and every later command reuses it:

storvia-cli login -d <your-domain>

You will be prompted for the token, which is verified against the server before it is saved. Nothing is uploaded during this step.

• storvia-cli whoami lists the domains you have tokens for.
• storvia-cli logout -d <your-domain> removes a stored token.

Upload a folder#

storvia-cli sync -d <your-domain> <folder-path>

Files that were already uploaded successfully are skipped, so re-running the command after a failure only sends what is missing. A file that has changed since its last upload is sent again.

Replacing files that already exist#

N7 Storage refuses to overwrite by default, so uploading to a path that is already taken fails with a conflict:

Failed to upload a.png: upload rejected with status 409: file already exist
(the file already exists on the server; re-run with --overwrite to replace it)

Add --overwrite to replace them instead:

storvia-cli sync -d <your-domain> --overwrite <folder-path>

--rescan does not do this. It only re-examines your local upload record so unchanged files are sent again; the server still refuses to overwrite. Use --rescan --overwrite together to re-send everything and replace what is already there.

Fixing unsupported names#

By default sync reports any file whose name N7 Storage will reject, and uploads the rest:

2026/08/26 04:25:45 2 name(s) will be rejected by storvia. Re-run with --autocorrect=auto or --autocorrect=interactive to fix them:
2026/08/26 04:25:45   My Photos (suggested: My-Photos)
2026/08/26 04:25:45   My Photos/my holiday photo.jpg (suggested: my-holiday-photo-baa0c.jpg)

Folders are reported too, because a folder name that N7 Storage rejects makes every file inside it unreachable.

Add --autocorrect to rename them on disk before uploading:

• --autocorrect=auto renames everything it can without asking.
• --autocorrect=interactive shows each proposed rename and lets you accept it, type your own name, or skip the file.

storvia-cli sync -d <your-domain> --autocorrect=auto <folder-path>

Every rename is printed:

2026/08/26 04:25:48 RENAMED folder: My Photos -> My-Photos (unsupported characters in folder name)
2026/08/26 04:25:48 RENAMED file: My-Photos/my holiday photo.jpg -> My-Photos/my-holiday-photo-1dd81.jpg (unsupported characters)

The -1dd81 is a short random suffix added to every automatically renamed file. Folders do not get one, so an existing folder on your domain is added to rather than duplicated.

Files with no extension at all, such as README, cannot be renamed automatically. They are reported and skipped.

Keeping the CLI up to date#

storvia-cli upgrade

This downloads the latest published build, verifies it against the published checksums, and replaces the binary you are running. If you are already on the latest build it does nothing.

• storvia-cli upgrade --check reports whether an upgrade is available without installing it.
• storvia-cli --version shows the version you have.

If storvia-cli was installed into a system directory such as /usr/local/bin, the upgrade needs the same permissions you used to put it there.

Check what was uploaded#

storvia-cli status -d <your-domain>

Cache: /home/you/.config/storvia-cli/storvia-cli.cache

  example.com
    FAILED           2 files      1.4 MB
    UPLOADED       317 files    842.6 MB

Add --filter FAILED to list the individual files along with the error the server returned.

CLI Command Reference#

• Commands :
  • sync <folder> : Uploads files from the specified directory.
  • login : Stores the service token for a domain.
  • logout : Removes the stored token for a domain.
  • whoami : Shows which domains have a stored token.
  • status : Shows what has been uploaded from this machine.
  • upgrade : Upgrades storvia-cli to the latest published version.
• Global flags :
  • -d, --domain <domain> : Target domain for file uploads. (Required)
  • --token <service-token> : Service token, overriding the stored one. (Optional)
  • -y, --non-interactive : Never prompt. Useful in scripts and CI.
  • --config <path> : Use a different config file.
  • -v, --version : Print the installed version.
• sync flags :
  • --autocorrect <auto|interactive> : Rename files and folders that N7 Storage would reject.
  • --overwrite : Replace files that already exist on the server instead of failing with a conflict.
  • --rescan : Force re-evaluation of all files, even if already marked uploaded. This is local-only and does not permit overwriting.
  • -c, --concurrency <n> : Number of concurrent uploads. (Default 10)
  • --cache <path> : Path to the cache file that tracks upload progress.
• status flags :
  • --filter <status> : List files with this status — UPLOADED, FAILED, PENDING or UPLOADING.
  • --limit <n> : Maximum number of files to list with --filter. (Default 20)
• login flags :
  • --no-verify : Store the token without checking it against the server first.
• upgrade flags :
  • --check : Report whether an upgrade is available, without installing it.
  • --force : Reinstall even if already up to date.
  • --target <version> : Install a specific published version instead of the latest.

API: Upload Files to N7 Storage#

• API :

  Copy

  	POST https://storvia.n7.io/v1/upload?domain_name={domain}&alias={resource_path}

• Request Headers :

  Copy

  	Authorization: Token <api-key-of-service-account>

  If using PostMan, set the Auth Type to No Auth. And then set the Authorization header in Headers section.

• Request Body :

  • Use a multipart/form-data form with the file to upload.
    
  Copy

  	form 'file=@"{file_path}"'

Explanation of Upload API Parameters#

• Query params :
  • domain_name: The domain where the file should be uploaded.
  • alias: The desired resource path (e.g., images/photo.jpg) for accessing the file later. It must follow the naming rules , and must be URL-encoded.
  • overwrite (optional): Set to true to replace a file that already exists at that alias. Without it, uploading to an existing alias returns 409. Supported on both this endpoint and the earlier one.
• Form Data :
  • file: The path to the local file being uploaded. The form field must be named file.

Example: Upload API Request#

• macOS / Linux

  Copy

  curl --request POST \
    --url 'https://storvia.n7.io/v1/upload?domain_name=example.com&alias=images%2Fphoto.jpg' \
    --header 'Authorization: Token <api-key-of-service-account>' \
    --form 'file=@/path/to/photo.jpg'

• Windows (PowerShell) — quote the URL and use the full file path:

  Copy

  curl.exe --request POST `
    --url "https://storvia.n7.io/v1/upload?domain_name=example.com&alias=images%2Fphoto.jpg" `
    --header "Authorization: Token <api-key-of-service-account>" `
    --form "file=@C:/Users/n7/Downloads/photo.jpg"

To replace a file that already exists, add &overwrite=true to the URL:

curl --request POST \
  --url 'https://storvia.n7.io/v1/upload?domain_name=example.com&alias=images%2Fphoto.jpg&overwrite=true' \
  --header 'Authorization: Token <api-key-of-service-account>' \
  --form 'file=@/path/to/photo.jpg'

Two things that are easy to get wrong:

• The alias is a query parameter, so any / in the path must be written as %2F — images%2Fphoto.jpg arrives as images/photo.jpg.
• The form field must be named file. --form 'upload=@...' is rejected.

Do not set a Content-Type header yourself — your HTTP client sets the correct multipart/form-data boundary automatically.

Example: Upload API Response#

A successful upload returns 201 Created:

{
	"key": "{domain}/xx/xx/xxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"alias": "images/photo.jpg"
}

Upload API Response Explanation#

Here,

• key : The full storage path of the uploaded file in N7 Storage. This is used internally to locate the file.
• alias : The resource path that can be used to access the file via your domain.

Common Errors#

Earlier API version#

The original endpoint remains available for existing integrations:

	POST https://storvia.n7.io/upload/{domain}/{resource_path}

It behaves the same way — including ?overwrite=true — but the resource path is part of the URL rather than a query parameter, so characters such as ? and # in a path can corrupt the request. New integrations should use /v1/upload.