Developer API

What the API actually is

The QNSQY Developer API is an HTTP/REST wrapper around the same local crypto engine that powers the CLI. Same qnsqy-core primitives, same .qs file format, same NIST-standardized algorithms, exposed for automation instead of interactive use. It is built for scripted, repeatable workflows: encrypt-on-upload, sign-on-release, batch-encrypt a backup set, rotate a password across a file tree, all driven from your code rather than a terminal.

Authentication: API key

Authentication mirrors how the CLI authenticates against the billing service: a single API key. Provide it on the command line with --api-key, or set the QNSQY_API_KEY environment variable so it never appears in shell history or process listings. The key is held in zeroizing memory, redacted from logs and debug output, and sent only as an HTTP Authorization: Bearer <key> header to the billing endpoint over HTTPS.

• Where keys come from: generate an API key from your account dashboard once you are on an API plan (see API plans).
• Transport: HTTPS only. The client refuses non-HTTPS billing URLs outside of localhost, and connections are pinned to the billing host.
• What the server sees: the key, the operation type, the file size in bytes, the algorithm level, and a client version string. Never the file, never the password, never key material.

# Keep the key out of shell history and argv
export QNSQY_API_KEY="qsk_live_your_api_key_here"

Example requests

The supported way to drive the API today is the qnsqy-api client binary. The verified commands are encrypt, decrypt, rekey, batch-encrypt, batch-decrypt, keygen, sign-keygen, shred, and usage. Signing happens as part of encrypt (via a signing key) and verification as part of decrypt; both operate on the local file.

# File is encrypted on your machine; only its size is reported for billing.
qnsqy-api encrypt --api-key "$QNSQY_API_KEY" \
  -i report.pdf -o report.pdf.qs \
  --kem-level level5 \
  --sign-key release.key --dsa-level level5 \
  --password-stdin < password.txt

qnsqy-api decrypt --api-key "$QNSQY_API_KEY" \
  -i report.pdf.qs -o report.pdf \
  --verify-key release.pub \
  --password-stdin < password.txt

qnsqy-api usage --api-key "$QNSQY_API_KEY" --format json

Under the hood, the client talks to the billing service over a small, Bearer-authenticated JSON surface. The verified endpoint base is https://api.quantumsequrity.com/api/v1, with usage routes /usage/authorize, /usage/complete, and /usage/balance. The example below is the authorization call the client makes before it encrypts locally, note that it sends a file size, not the file.

curl -X POST https://api.quantumsequrity.com/api/v1/usage/authorize \
  -H "Authorization: Bearer $QNSQY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "encrypt",
    "file_size_bytes": 1048576,
    "features": { "kem_level": "level5", "signing": "level5" }
  }'

The encrypt/sign HTTP payloads below are illustrative of how a future direct-call surface would read; they are not a published, fixed route contract. The route names and request bodies your code should depend on live in the documentation. For exact, verified behavior today, use the qnsqy-api client shown above.

# Illustrative encrypt-style request. Treat as pseudocode, not a guaranteed route.
curl -X POST https://api.quantumsequrity.com/api/v1/encrypt \
  -H "Authorization: Bearer $QNSQY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "algorithm": "ml-kem-1024+x25519", "aead": "aes-256-gcm" }'

# Illustrative sign-style request.
curl -X POST https://api.quantumsequrity.com/api/v1/sign \
  -H "Authorization: Bearer $QNSQY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "algorithm": "ml-dsa-87+ed25519" }'

Algorithms available over the API

The API exposes the same hybrid post-quantum primitives as the rest of QNSQY. Key encapsulation runs ML-KEM at three NIST levels, always hybridized with X25519. Signing runs ML-DSA at three levels, hybridized with Ed25519. Symmetric encryption is AES-256-GCM (default) or XChaCha20-Poly1305, with Argon2id for password-based key derivation.

• KEM: ML-KEM-512 / 768 / 1024 + X25519 (FIPS 203, hybrid).
• Signatures: ML-DSA-44 / 65 / 87 + Ed25519 (FIPS 204, hybrid).
• AEAD: AES-256-GCM or XChaCha20-Poly1305.
• KDF: Argon2id, with configurable memory / iterations / parallelism.

Note: recipient-keypair (public-key) encryption is intentionally not exposed through the qnsqy-api client; it is rejected rather than silently downgraded. For multi-recipient and recipient-keypair workflows, use the main qnsqy binary. Algorithms standardized under FIPS 203/204 are NIST-standardized; QNSQY is not FIPS 140-3 / CMVP validated.

Plans, credits, and limits

API plans share the same credit system as the apps. ML-KEM-512 + ML-DSA-44 operations are always free, on every plan, with no credit cost. Heavier algorithms (for example ML-KEM-1024, ML-DSA-87) consume credits based on file size. Decrypt, verify, keygen, and shred are always free. Per-file size is capped at 25 GB on the API tier.

Credit formula for credit-costing algorithms: max(1, ceil(file_size / 1 GB)) per operation. ML-KEM-512 + ML-DSA-44 are always free on all plans. Full terms, the live plan table, and the self-serve checkout are on the pricing page.

Privacy and security model

• File content stays local. Encryption and decryption run on your machine via qnsqy-core. Only the file size in bytes is reported for billing.
• Keys are protected in transit and memory. The API key is stored in zeroizing memory, redacted from debug output, and sent only as a Bearer token over HTTPS.
• HTTPS enforced. The client rejects plaintext billing URLs (except localhost for development) and pins the billing host.
• Fail-closed billing. If the operation is not authorized, it does not run. The client reports completion only after a successful local operation.
• Hardened core. On Linux, core dumps are disabled before any secret is loaded, so a crash cannot spill password or key material.

Same standing disclaimer as the rest of the site: QNSQY uses NIST-standardized post-quantum algorithms but is not FIPS 140-3 / CMVP validated, and is not SOC 2, PCI DSS, or HIPAA certified. Your auditor owns the compliance call. See Security for the full breakdown.

Roadmap (in development)

A few things people ask for are not shipping yet. We would rather say so than imply otherwise.

• Roadmap — direct HTTP encrypt/sign routes. The illustrative /encrypt and /sign payloads above describe a direct-call surface that is not a finalized, published route contract today. Until it is, integrate via the qnsqy-api client.
• Roadmap — parallel batch. Batch operations currently process files sequentially; the parallelism flag is reserved and not yet implemented.
• Roadmap — recipient-keypair encryption over the API. Available in the main qnsqy binary today; not exposed through the API client.