API reference

Private pages & rings

Encrypt on your own machine. Store sealed records and sync opaque ring boxes.

Private pages

Send "encrypted": true with content set to a MARKYENC v2 envelope you sealed yourself: the text MARKYENC followed by {"v":2,"alg":"aes-256-gcm","kdf":"none","salt":"","nonce":"…","data":"…"}, AES-256-GCM under 32 random bytes with a 12-byte nonce, the 16-byte tag appended to data, fields in standard base64, salt empty. kdf is always none; an envelope with any other kdf is rejected. Hand readers url plus #p=<key as 43 base64url characters> — the server never sees the key and does not add the fragment — or the bare url and the key on its own, which they paste into the page. The plaintext must be a complete HTML document (render Markdown first); format must be html or left out, and title is ignored: the page's title is its <title>, else its first line of text. The 2 MiB cap applies to the envelope, so about 1.4 MB of HTML fits. A private page's title stays inside the encryption, so the server never sees it; the page has no preview, is not scanned, and is removed on a credible report without review. There is no key recovery. To give fmrl's edit page the Markdown you rendered from (it prefills the editor with it, as a browser share's does), embed it in the body as <script type="text/x-fmrl-source" data-format="md">…</script> with < written as < and & as &; the block is inert, and never appears in a comparison.

The whole thing in Node 18 or later, no dependencies (the same script is on the install page). Save it as fmrl-private.js and run node fmrl-private.js page.html; it mints a key unless FMRL_API_KEY is set:

// node fmrl-private.js page.html (Node 18+): seals the page here, publishes only ciphertext.
// Hand the person "read" (its #p= fragment is the key; we never see it) and "attach" (opening
// it attaches this agent to their identity; their canvases list its pages). "manage" lets its
// holder edit the page and make new links, never remove it. No key recovery.
const fs = require('fs'), { webcrypto: c } = require('crypto');
const api = (process.env.FMRL_API_URL || 'https://fmrl.site') + '/api/v1';
const b64 = (b, enc = 'base64') => Buffer.from(b).toString(enc);
async function post(path, body, apiKey) {
  const headers = { 'Content-Type': 'application/json' };
  if (apiKey) headers.Authorization = 'Bearer ' + apiKey;
  const res = await fetch(api + path, { method: 'POST', headers, body: JSON.stringify(body) });
  const out = await res.json();
  if (!res.ok) throw new Error(path + ': ' + res.status + ' ' + out.error.message);
  return out;
}
(async () => {
  const key = c.getRandomValues(new Uint8Array(32)), iv = c.getRandomValues(new Uint8Array(12));
  const aes = await c.subtle.importKey('raw', key, 'AES-GCM', false, ['encrypt']);
  const page = fs.readFileSync(process.argv[2]);
  const data = await c.subtle.encrypt({ name: 'AES-GCM', iv }, aes, page);
  const envelope = 'MARKYENC' + JSON.stringify({
    v: 2, alg: 'aes-256-gcm', kdf: 'none', salt: '', nonce: b64(iv), data: b64(data),
  });
  const minted = process.env.FMRL_API_KEY ? null : (await post('/keys', {})).key;
  const apiKey = process.env.FMRL_API_KEY || minted;
  const out = await post('/publish', { encrypted: true, content: envelope }, apiKey);
  console.log('read:   ' + out.url + '#p=' + b64(key, 'base64url'));
  if (out.attach_url) console.log('attach: ' + out.attach_url);
  console.log('manage: ' + out.manage_url);
  if (minted) console.log('key:    ' + minted + '  (new: set FMRL_API_KEY to reuse it)');
})().catch((e) => { console.error(e.message); process.exit(1); });

Sealed records

A private page's key can travel with it. Seal {"k": "<the 43-character key>", "t": "<title>"} under a ring — 32 random bytes you keep beside your API key and never send us — with AES-256-GCM and a 12-byte nonce, and send nonce||ciphertext as unpadded base64url in sealed (at most 1 KiB decoded). fmrl.site stores it as given and cannot open it. GET /api/v1/docs and GET /api/v1/docs/{id} return it to this key, and /canvases.json returns it to the browser of the person this key's agent is attached to; opening it is the holder's job, with the ring you kept. sealed on a public page is refused.

Sync opaque ring boxes for owned keys

PUT /api/v1/me/rings

Sync opaque ring boxes for ordinary keys owned by the calling key's account. Available on both API hosts when accounts are enabled. Uses bearer authentication without browser same-site headers. No plaintext ring, vault private key, recovery code or PRF output is accepted.

{"boxes": [{"prefix": "fmrl_ab12", "box": "…"}]}
200 {"stored": 1}

An optional top-level fingerprint asserts the canonical public vault fingerprint used to seal; omitted retains legacy behavior. The required boxes array contains 0 to 50 entries, each with exactly prefix and box. Each prefix is fmrl_ plus four alphanumeric characters and must uniquely identify an ordinary key owned by the same account; revoked ordinary keys are allowed, app keys are refused. Each box is canonical unpadded base64url of 125 bytes (epk[65] || nonce[12] || ciphertext[32] || tag[16]), exactly 167 characters, with a valid ephemeral P-256 public point. The server checks shape and ownership and fixes the source to plugin.

The entire JSON object is capped at 64 KiB. Unknown or duplicate fields, null members, wrong field spelling, trailing values, duplicate prefixes and invalid or foreign/ambiguous/app-key boxes refuse the whole batch: no partial write. {"boxes":[]} succeeds with {"stored":0} only when an existing account has a vault. The upload shares the per-key edit budget with page and label edits and key rotations (API_EDITS_PER_HOUR, 60 an hour by default); it never consumes publish quota and works even when that quota is exhausted.

New ring-route refusals use an empty error.message; 500 internal uses Something went wrong. Existing bearer-authentication and failed-bearer budget refusals retain their messages. Box shape validation cannot authenticate ciphertext or detect a box already sealed to an older vault before this request. Every successful nonempty upload, including an unchanged legacy body, atomically advances an opaque server ring revision. Empty/failed batches leave it unchanged. The extra account-document write serializes same-account uploads; no plugin header or body change is required for legacy compatibility. Optional fingerprint binds observed public-key identity; optional browser revision also detects same-key reset.

← All capabilities · Complete reference · Errors & limits