API
Everything the web app does, your code can do too. Encryption always happens on your side; the API only ever sees ciphertext.
Quick start
The official client handles the crypto. Start here unless you have a reason not to.npm install @clickswave/silocat-clientimport { Silocat } from '@clickswave/silocat-client';
const silo = new Silocat({ apiKey: process.env.SILOCAT_API_KEY });
// Encrypted in your process. Ciphertext is all that leaves it.
const file = await silo.upload(bytes, {
name: 'contract.pdf',
password: 'correct-horse-battery-staple'
});
// A link anyone can open. It carries no key.
const { url } = await silo.share(file.id, { type: 'public' });
// Read it back.
const plaintext = await silo.download(file.id, {
password: 'correct-horse-battery-staple'
});Authentication
One key per account, sent asX-Api-Key.Find your key in Settings → API. It identifies your account outright: anything holding it can read, share and delete your files, so keep it in the same place you keep other secrets and never ship it to a browser.
You can rotate it from the same screen. Rotation is immediate and total, with no overlap window, so anything still using the old key breaks until you paste the new one in.
Client reference
Errors throwSilocatError with .status and .body.storage() Bytes used, total and free.listFiles({ folderId, starred, shared }) Omit folderId for the root.listFolders({ parentId }) Folders at one level.createFolder(name, { parentId }) Returns the new folder.upload(data, { name, password, mime, folderId, onProgress }) Uint8Array, ArrayBuffer or Blob. Omit password to upload unencrypted, readable by us.download(id, { password, onProgress }) Returns plaintext bytes.share(id, { type }) 'public', 'once' or 'off'.trash(id) / restore(id) Recoverable until the retention window expires.deleteForever(id) Irreversible.Why there is a library
Silocat is zero-knowledge, so the API cannot accept a file. It accepts ciphertext. Doing that by hand means deriving a key with Argon2id at libsodium's MODERATE limits, splitting the file into 100 MB chunks, and encrypting each one with XChaCha20-Poly1305 under a fresh 24-byte nonce, with a single salt per file.
Every one of those has to match exactly. Get a parameter wrong and the upload still succeeds, but the file can never be decrypted again, by you or by us. The library is the reference implementation, which is why the raw endpoints below are documented as a fallback rather than the recommended path.
Two things no client can change: lose the password and the file is gone, and a share link never carries the key. Send the password through a different channel or the link alone is enough to read the file.
Raw HTTP
Every route below is callable with your API key. Send it asX-Api-Key; responses are application/json.Account
Who you are and how much room you have.{
"success": {
"used": 2206833100,
"total": 10737418240,
"free": 8530585140
}
}