API Reference

Security model

The v1 note API is zero-knowledge. The server stores only ciphertext and the key stays in the URL fragment — plaintext never leaves your machine.

Authentication

Creating a note works without authentication, within the anonymous limits below. With a vn_ API key from your dashboard (accounts are free), notes get the account limits and appear in your history. Reading and peeking are unauthenticated. Creating a stream needs an account.

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. Without authentication, creation is rate-limited per IP address.

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

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",
  "kdf":            "sha256",       // or "pbkdf2-sha256-600k" — see Security model
  "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,
  "kdf":            "sha256"
}

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. The stream token in the URL path includes the key, so it reaches the server with each request; it is not stored. 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/n/TOKEN#SECRET");
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/n/TOKEN#SECRET")
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