API Reference

Security model

VoidNote is zero-knowledge. The server stores only ciphertext — plaintext never leaves your machine.

Authentication

Creating notes requires a vn_ API key from your dashboard. Reading and peeking are unauthenticated.

Create a note. You encrypt the content; the server generates a tokenId and returns a base URL. Append #secret to form the full shareable link.

{
  "token":     "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "url":       "https://voidnote.net/n/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "expiresAt": "2025-01-01 12:00:00",
  "viewLimit": 1
}

Append #<secret> to url — that's the shareable link. The secret never touches the server.

Fetch the encrypted blob and decrement the view count. Returns the ciphertext — decrypt locally. On the final view the note is permanently destroyed.

{
  "token":          "a1b2c3...",
  "encrypted":      "...",          // hex — AES-256-GCM ciphertext
  "iv":             "...",          // hex — 12-byte nonce
  "algorithm":      "AES-256-GCM",
  "keyDerivation":  "SHA-256",      // key = SHA-256(hex_decode(secret))
  "viewsRemaining": 0,
  "destroyed":      true
}

Peek at metadata without consuming a view. Use this to check if a note still exists before revealing it.

{
  "token":          "a1b2c3...",
  "exists":         true,
  "type":           "secure",
  "createdAt":      "2025-01-01 10:00:00",
  "expiresAt":      "2025-01-01 11:00:00",
  "viewLimit":      1,
  "viewsRemaining": 1
}

Vault

Encrypted file storage. Upload once, download once — the file is destroyed after the first download.

Streams

Live encrypted channels over SSE. The server relays ciphertext only — keys never leave the sender. Streams auto-expire after their TTL and can be closed early at any time.

SDK examples

All SDKs handle encryption/decryption automatically. No crypto boilerplate needed.

import voidnote

result = voidnote.create(
    "my secret API key",
    api_key="vn_...",
    max_views=1,
    expires_in=1,   # hours
)
print(result.url)   # https://voidnote.net/n/<token>#<secret>

import voidnote

note = voidnote.read("https://voidnote.net/n/<token>#<secret>")
print(note.content)
print(f"{note.views_remaining} views remaining")

import voidnote

meta = voidnote.peek("https://voidnote.net/n/<token>#<secret>")
print(meta.exists, meta.views_remaining, meta.expires_at)

import { create } from "@voidnote/sdk";

const result = await create("my secret", {
  apiKey: "vn_...",
  maxViews: 1,
  expiresIn: 1,
});
console.log(result.url);  // https://voidnote.net/n/<token>#<secret>

import { read } from "@voidnote/sdk";

const note = await read("https://voidnote.net/n/<token>#<secret>");
console.log(note.content);

result, err := voidnote.Create("my secret", voidnote.CreateOptions{
    APIKey:    "vn_...",
    MaxViews:  1,
    ExpiresIn: 1,
})
fmt.Println(result.URL)

import net.voidnote.*;

CreateResult result = VoidNote.create(
    "my secret API key",
    CreateOptions.of("vn_...")
        .withMaxViews(1)
        .withExpiresIn(1));
System.out.println(result.url());

ReadResult note = VoidNote.read("https://voidnote.net/note/TOKEN");
System.out.println(note.content());
System.out.println(note.destroyed() ? "destroyed" : note.viewCount() + " views");

StreamHandle stream = VoidNote.createStream(
    StreamOptions.of("vn_...").withTitle("Deploy log"));
System.out.println("share: " + stream.url);
stream.write("Build started...");
stream.write("All tests passed");
stream.close();

import VoidNote

let result = try await VoidNote.create(
    "my secret API key",
    apiKey: "vn_...",
    maxViews: 1,
    expiresIn: 1)
print(result.url)

let note = try await VoidNote.read("https://voidnote.net/note/TOKEN")
print(note.content)
print("views remaining: \(note.viewsRemaining)")

let stream = try await VoidNote.createStream(
    apiKey: "vn_...", title: "Deploy log")
print("share: \(stream.url)")
try await stream.write("Build started...")
try await stream.write("All tests passed")
try await stream.close()

Rate limits