Documentation

1. Sign in to the dashboard with Google and create an API key under API keys. Keys start with sb_live_; we only store a hash, so copy it when it is shown.

2. Send it on every request, either way:

x-api-key: sb_live_...
# or
Authorization: Bearer sb_live_...

3. Upload a file, query it, download it:

export SOV_KEY=sb_live_...

curl -H "x-api-key: $SOV_KEY" \
  -F file_id=orders-2023 -F file=@orders_2023.sql.gz \
  https://api.sovereignbyte.tech/v1/vault/direct-upload

curl -H "x-api-key: $SOV_KEY" \
  -d file_id=orders-2023 \
  --data-urlencode "sql_query=SELECT status, count(*) AS n FROM orders GROUP BY status" \
  https://api.sovereignbyte.tech/v1/vault/pushdown-query

curl -H "x-api-key: $SOV_KEY" -o orders_2023.sql.gz \
  https://api.sovereignbyte.tech/v1/vault/download/orders-2023

Upload the export you already have. Each file becomes one or more tables. Any of the text formats can be gzipped (.gz).

Table names. A CSV, JSON or Parquet file becomes one table named after the file (orders_2023.csv.gz → orders_2023); you can also use data. A dump or SQLite file keeps its own table names.

Column types. In dumps, numbers written without quotes become numbers; quoted values stay exact text, so codes like 000123 keep their zeros. In CSV files an empty value is read as NULL.

Not supported yet: pg_dump custom or directory format (-Fc, -Fd; use plain SQL), .zip and .tar archives, Excel files, and dump values that are function calls other than the ones sqlite3 writes.

The Sovereign CLI (cli/sov.py) runs locally on Linux and macOS with Python 3. It automates columnar compression, streaming uploads up to 1 GB, and cryptographic directory packaging.

1. Convert Tabular Data to Parquet (sov to-parquet)

Convert raw CSV, TSV, or JSON into compressed columnar Parquet via DuckDB streaming (yielding 70%–85% size reduction and 10x faster query pushdown):

# Convert local file to ultra-compact .parquet (uses zstd compression)
python3 sov.py to-parquet orders.csv

# Or convert and upload directly to Sovereign Cloud:
python3 sov.py to-parquet orders.csv --api-key sb_live_...

2. Direct Upload from Terminal (sov upload)

Upload any dataset up to 1 GB. Adding --to-parquet automatically converts tabular files before uploading:

export SOVEREIGN_API_KEY=sb_live_...

# Upload and auto-convert tabular datasets:
python3 sov.py upload dataset.csv --to-parquet

# Upload any existing archive or database dump:
python3 sov.py upload database_backup.sql.gz

3. Package & Auto-Split Large Directories (sov pack)

For directories or multi-gigabyte exports, sov pack automatically compresses and splits data at clean newline boundaries into self-contained .spst partitions with SHA-256 Merkle root attestation:

# Pack a directory or huge export (auto-splits without severing lines):
python3 sov.py pack /path/to/data_dir -o my_archive

# Unpack and verify SHA-256 Merkle roots locally:
python3 sov.py unpack my_archive_part_1.spst -o ./restored_data

Connect Claude Desktop, Cursor, Antigravity, and VS Code directly to your Sovereign Cloud Vault using our official MCP Server (mcp/sovereign_mcp_server.py).

AI agents gain the ability to query multi-gigabyte datasets via SQL pushdown, inspect schemas, auto-convert tabular datasets to Parquet, and upload/download vault files without manual dashboard interaction.

Claude Desktop Setup

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "sovereign-cloud": {
      "command": "python3",
      "args": ["/absolute/path/to/sovereign-aws-cloud-enterprise/mcp/sovereign_mcp_server.py"],
      "env": {
        "SOVEREIGN_API_KEY": "sb_live_..."
      }
    }
  }
}

Cursor & Windsurf Setup

In Cursor Settings → Features → MCP Servers, add a new server:

Name: sovereign-cloud
Type: command
Command: python3 /absolute/path/to/sovereign_mcp_server.py

POST /v1/vault/direct-upload (multipart form) with file and file_id, a name you choose (letters, digits, . _ -). Uploading again with the same file_id replaces the file.

After upload we compress the file losslessly in the background. Downloads always return the bytes you uploaded.

POST /v1/vault/pushdown-query with form fields file_id and sql_query. Queries use DuckDB SQL: joins between the tables of one file, CTEs, window functions, regular expressions and JSON functions all work.

{
  "status": "success",
  "latency_ms": 6,
  "truncated": false,
  "tables": ["orders", "customers"],
  "results": [{"status": "PAID", "n": 1820}, {"status": "REFUNDED", "n": 41}]
}

GET /v1/vault/tables?vault_file_id=orders-2023 lists a file's tables without running a query. The first query on a new file takes longer while we prepare it; later queries are fast.

GET    /v1/vault/files                 # your files, sizes and status
GET    /v1/vault/download/{file_id}    # the original bytes
DELETE /v1/vault/files/{file_id}       # removes the file and every copy we made
GET    /v1/vault/quota                 # storage used and plan limit

Reaching a limit pauses new uploads or queries; it never deletes files or adds charges.

Errors return JSON: {"detail": "..."}. Is the service itself up? See the status page or GET /v1/status.

A cron job or CI step that archives last night's dump, with the date in the file_id:

# PostgreSQL
pg_dump "$DATABASE_URL" | gzip > db.sql.gz
# or MySQL
mysqldump --single-transaction mydb | gzip > db.sql.gz

curl -fsS -H "x-api-key: $SOV_KEY" \
  -F file_id=db-$(date +%F) -F [email protected] \
  https://api.sovereignbyte.tech/v1/vault/direct-upload

Store the key in your CI's secret store, never in the repository. For files above 1 GB, split dumps by table (pg_dump -t, mysqldump mydb table), bundle directories with sov pack, or convert tabular data with sov to-parquet.

• Files are stored in Amazon S3 in AWS Mumbai (ap-south-1), encrypted at rest.
• Before a stored file is replaced with a smaller compressed copy, the copy is decoded and its SHA-256 and size compared with the original. If anything differs, the original stays.
• Archives made with our desktop app (.spst v2) carry SHA-256 hashes for each block, checked when they are read. A mismatch returns an error, never data.
• Your SQL runs in a sealed, read-only session for that one file, with no access to other files, the server or the network.