Blanc API

Read a person's notes in Blanc and add to them, with their permission. Your app connects through Blanc's consent screen, and the person can disconnect it at any time.

Overview

• Base address: https://api.blancnote.app. Everything lives under /v1.
• For apps other people use. Every app connects with OAuth 2.0 and PKCE, and the person approves it on Blanc's consent screen. There are no API keys and no personal tokens.
• What an app can do: list and read notes as HTML, Markdown or plain text; create notes, edit them, add to them, move them to the trash and back; read notebooks and tags; and poll for everything that changed.
• JSON throughout, with camelCase fields. Timestamps are ISO 8601 in UTC with milliseconds, such as 2026-10-21T13:14:16.123Z.
• The OpenAPI document is at https://api.blancnote.app/v1/openapi.json, for code generators and API tools. The reference on this page is generated from it.

Before an app changes a note's text, Blanc keeps a version of it that the person can restore, and the API can move a note to the trash but can't delete it for good. Trash, versions and locked notes has the limits.

Register your app

Register your app in Blanc, under Settings → Connected apps → Register an app. You'll need:

• a name (up to 60 characters) and a developer name, yours or your company's (up to 100);
• one or more redirect URIs, up to 10;
• optionally a description (up to 500 characters), a homepage (an https address), and a logo: a PNG, JPEG or WebP image of about 75 KB or less (it's stored as a data: URI, which can be at most 100 KB).

You get a client ID at once. There's no client secret: every app uses PKCE instead, so a native app has nothing to hide in its binary. An account can register up to 20 apps. Deleting an app ends every connection anyone has made to it.

Redirect URIs are where Blanc sends the person back. Each is one of:

• an https address on any host, for a backend, such as https://example.com/blanc/callback;
• a custom scheme your native app owns, such as com.example.notes:/oauth. Schemes that run or read something (javascript:, data:, file: and the like), other web schemes, and Blanc's own are refused;
• an http loopback address, http://127.0.0.1/… or http://[::1]/…, for a CLI or a native app that listens on the device. A registered loopback address matches on any port (RFC 8252), so your app can listen wherever is free.

Apart from the loopback port, a redirect URI matches exactly: no prefixes and no wildcards. http://localhost isn't accepted, since localhost can resolve somewhere else (use 127.0.0.1 or [::1]), and neither is a fragment (#…) or a user name in the address.

Verification. Until Blanc verifies an app, its consent screen says Blanc hasn't reviewed this app above the Allow button. Verification is a label, not a gate: an unverified app works exactly the same. It covers what the consent screen shows and where codes go, so changing the app's name, developer name, logo or redirect URIs clears it. To ask for it, write to api@blancnote.app.

Connect a person's account

Blanc uses OAuth 2.0's authorization code flow with PKCE (RFC 7636), and only that: no implicit grant, no password grant, no client credentials. PKCE is required for every app, backends included.

Scopes

Ask for what your app needs. The consent screen lists each scope as a sentence, never as a scope string.

Most apps that write ask for notes:write offline; notes:write already includes reading.

Step by step

1. Make a PKCE verifier and challenge. The verifier is a random string of 43 to 128 characters from A–Z a–z 0–9 - . _ ~; 32 random bytes in base64url is 43. The challenge is the base64url SHA-256 of the verifier, without padding. Blanc accepts only the S256 method. Make a new pair, and a new state, every time.

2. Send the person to Blanc. Open this address in their browser (for a native app, the system browser or an authentication session, not a web view you control):

https://api.blancnote.app/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fblanc%2Fcallback
  &scope=notes%3Awrite%20offline
  &state=RANDOM_STATE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

3. The person decides. Blanc's consent screen shows your app's name, logo and developer, what it wants to do, and the unverified line if it applies. The person signs in with their Blanc email and password on that screen, every time, then chooses Allow or Cancel. Your app never sees the password. The screen stays valid for ten minutes; after that, the person sees This page has expired and has to start again from your app.

4. Blanc sends them back to your redirect URI with code and your state, or with error=access_denied if they cancelled. Check that state is the one you sent before you do anything else.

5. Exchange the code, within ten minutes, from wherever holds the verifier. The body is form-encoded:

curl https://api.blancnote.app/v1/oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://example.com/blanc/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d code_verifier=THE_VERIFIER

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "3c9f0d2a8b7e61f4a05d9c2e.…",
  "scope": "notes:write offline"
}

redirect_uri must be exactly the one the authorization request sent, port included. A code works once: presenting it a second time ends the person's whole connection to your app, on every device, because a second use means someone else has the code. scope says what was granted.

6. Call the API with Authorization: Bearer <access_token>. An access token lasts one hour. Treat it as opaque.

7. Refresh, if you asked for offline, when the access token expires or a call answers 401:

curl https://api.blancnote.app/v1/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=THE_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID

Every refresh returns a new refresh token, and the one you sent stops working at once. Save the new one before you use the new access token. Sending a refresh token that was already used ends every refresh token descended from the same sign-in (access tokens already issued keep working until they expire), and there's no grace period, so an app that loses a refresh response has to send the person through the flow again. A refresh token expires 90 days after it was issued, so an app that refreshes at least once every 90 days keeps its connection. Add scope to a refresh to get an access token that can do less than the grant; you can't get more.

Refresh one at a time. Two refreshes with the same token at once count as a replay: one fails with invalid_grant, and the other's new refresh token is ended with it, so the person has to connect again. If several parts of your app can notice an expired token, make them wait for a single refresh, as the backend example below does.

8. Disconnect. For your app's own Disconnect button, revoke either token, even an access token that has expired (RFC 7009). The whole connection goes, with every token under it.

curl https://api.blancnote.app/v1/oauth/revoke -d client_id=YOUR_CLIENT_ID -d token=EITHER_TOKEN

People can also disconnect your app themselves, in Settings → Connected apps. Either way, its next call answers 401 invalid_token, and its next refresh answers invalid_grant.

A person has one connection to your app, however many times they connect. Connecting again replaces what it may do with the scopes asked for this time, so ask for everything you need each time. Connecting again without offline ends every refresh token your app holds for that person, on every device.

Example: a backend

A web app's server, in Node.js 18 or later with no dependencies; save it as connect.mjs. It keeps the verifier on the server, exchanges the code there, and keeps the tokens there. Register REDIRECT_URI exactly.

import http from "node:http";
import crypto from "node:crypto";

const BLANC = "https://api.blancnote.app";
const CLIENT_ID = process.env.BLANC_CLIENT_ID;
const REDIRECT_URI = process.env.BLANC_REDIRECT_URI; // e.g. https://example.com/blanc/callback

const pending = new Map(); // state → verifier, for the ten minutes a code lives
let tokens = null;         // a real app keeps these per user, encrypted at rest

http.createServer(async (req, res) => {
  const url = new URL(req.url, REDIRECT_URI);

  if (url.pathname === "/blanc/connect") {
    const verifier = crypto.randomBytes(32).toString("base64url");
    const state = crypto.randomBytes(16).toString("base64url");
    pending.set(state, verifier);
    setTimeout(() => pending.delete(state), 10 * 60 * 1000);
    const authorize = new URL("/v1/oauth/authorize", BLANC);
    authorize.search = new URLSearchParams({
      response_type: "code",
      client_id: CLIENT_ID,
      redirect_uri: REDIRECT_URI,
      scope: "notes:write offline",
      state,
      code_challenge: crypto.createHash("sha256").update(verifier).digest("base64url"),
      code_challenge_method: "S256",
    });
    res.writeHead(302, { Location: authorize.href }).end();
    return;
  }

  if (url.pathname === new URL(REDIRECT_URI).pathname) {
    const state = url.searchParams.get("state");
    const verifier = pending.get(state);
    pending.delete(state);
    if (!verifier) return void res.writeHead(400).end("That sign-in link is old or unknown. Try again.");
    if (url.searchParams.has("error")) return void res.end(`Not connected (${url.searchParams.get("error")}).`);

    const r = await fetch(`${BLANC}/v1/oauth/token`, {
      method: "POST",
      body: new URLSearchParams({
        grant_type: "authorization_code",
        code: url.searchParams.get("code"),
        redirect_uri: REDIRECT_URI,
        client_id: CLIENT_ID,
        code_verifier: verifier,
      }),
    });
    const body = await r.json();
    if (!r.ok) return void res.writeHead(502).end(`Blanc said ${body.error}.`);
    tokens = body;
    res.end("Connected to Blanc.");
    return;
  }

  res.writeHead(404).end();
}).listen(3000);

// Calls the API, refreshing once when the access token has expired. Callers
// that hit a 401 together share one refresh: two refreshes with the same
// token at once count as a replay, which ends the connection.
let refreshing = null;

async function blanc(path, init = {}) {
  const call = () => fetch(BLANC + path, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${tokens.access_token}` },
  });
  let res = await call();
  if (res.status === 401 && tokens.refresh_token) {
    refreshing ??= refresh().finally(() => { refreshing = null; });
    await refreshing;
    res = await call();
  }
  return res;
}

async function refresh() {
  const r = await fetch(`${BLANC}/v1/oauth/token`, {
    method: "POST",
    body: new URLSearchParams({
      grant_type: "refresh_token",
      refresh_token: tokens.refresh_token,
      client_id: CLIENT_ID,
    }),
  });
  const body = await r.json();
  if (body.error === "invalid_grant") { tokens = null; throw new Error("Reconnect Blanc"); }
  if (!r.ok) throw new Error(`Blanc said ${body.error}`);
  tokens = body; // save the new pair before anything else: the old refresh token is dead
}

Example: a native app or CLI

A command-line tool, in Node.js 18 or later with no dependencies, that connects through a loopback redirect and adds a line to a note; save it as blanc-append.mjs. Register the redirect URI http://127.0.0.1/callback: the tool listens on any free port, and the registered address matches it. A native app works the same way, or with its own custom scheme instead of the loopback server.

#!/usr/bin/env node
// node blanc-append.mjs "text to add" [note id]
import http from "node:http";
import crypto from "node:crypto";
import { execFile } from "node:child_process";

const BLANC = "https://api.blancnote.app";
const CLIENT_ID = process.env.BLANC_CLIENT_ID;
const [text, noteId] = process.argv.slice(2);

const verifier = crypto.randomBytes(32).toString("base64url");
const state = crypto.randomBytes(16).toString("base64url");

// Listen on any free port on the loopback address.
const server = http.createServer();
await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;

const code = await new Promise((resolve, reject) => {
  server.on("request", (req, res) => {
    const url = new URL(req.url, redirectUri);
    if (url.pathname !== "/callback") return void res.writeHead(404).end();
    res.end("Done. You can close this tab.");
    server.close();
    if (url.searchParams.get("state") !== state) reject(new Error("state doesn't match"));
    else if (url.searchParams.has("error")) reject(new Error(url.searchParams.get("error")));
    else resolve(url.searchParams.get("code"));
  });
  const authorize = new URL("/v1/oauth/authorize", BLANC);
  authorize.search = new URLSearchParams({
    response_type: "code",
    client_id: CLIENT_ID,
    redirect_uri: redirectUri,
    scope: "notes:write",
    state,
    code_challenge: crypto.createHash("sha256").update(verifier).digest("base64url"),
    code_challenge_method: "S256",
  });
  console.log(`Opening ${authorize.href}`);
  const opener = { darwin: "open", win32: "explorer" }[process.platform] ?? "xdg-open";
  execFile(opener, [authorize.href]);
});

const tokenRes = await fetch(`${BLANC}/v1/oauth/token`, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    redirect_uri: redirectUri, // exactly as sent, port included
    client_id: CLIENT_ID,
    code_verifier: verifier,
  }),
});
const tokens = await tokenRes.json();
if (!tokenRes.ok) throw new Error(`${tokens.error}: ${tokens.error_description}`);

// Add to the note given, or make a new one.
const res = await fetch(BLANC + (noteId ? `/v1/notes/${encodeURIComponent(noteId)}/append` : "/v1/notes"), {
  method: "POST",
  headers: {
    Authorization: `Bearer ${tokens.access_token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ markdown: text }),
});
const note = await res.json();
if (!res.ok) throw new Error(`${note.error}: ${note.message}`);
console.log(`${note.title}  ${note.url}`);

When connecting fails

Before Blanc trusts your request, it can't send anything back to you, so the person sees a Blanc page saying the link can't connect an app. That happens when client_id or redirect_uri is missing, the app is unknown or turned off, or the redirect URI isn't one the app registered. Blanc never redirects to an address it hasn't checked. Wrong passwords on the consent screen are limited to 20 every 15 minutes from one address; past that, the person sees Too many attempts.

After that, problems go back to your redirect URI as error, error_description and your state:

The token and revoke endpoints answer errors as RFC 6749 describes, { "error": "…", "error_description": "…" }:

A refresh that fails with invalid_grant means the person has to connect again. That's a promise: a revoked, expired or already-used refresh token always answers invalid_grant, and retrying can't help, so show a Reconnect button.

Making requests

Send the access token on every call:

curl https://api.blancnote.app/v1/me -H "Authorization: Bearer $TOKEN"

{
  "userId": "LXEWQrcmsEQBYnyp-6wy9chTD7GQPMTbAiWHF5IaSIE",
  "app": { "clientId": "blanc_Xq3vN8rTkL2pW9yZb4cD1e", "name": "Morning" },
  "scopes": ["notes:write", "offline"]
}

GET /v1/me is the "is my token working" call, and any scope will do. userId is how your app tells its users apart: it's stable for one account as your app sees it, and different for every app, so apps can't match up their users. With the profile scope it adds displayName, when the account has a name or a nickname.

• Writes send JSON, with Content-Type: application/json.
• Unknown fields and parameters are refused. The notes, notebooks and tags endpoints answer an unknown query parameter or body field, or a parameter sent twice, with a 400, so a misspelt filter fails loudly instead of quietly returning everything.
• Ids are opaque strings. A note's id looks like note-1792588456123-k3x9; don't parse it.
• Successful resource responses aren't cacheable (Cache-Control: private, no-store).

Notes

Title and body

A note in Blanc is a title heading, then everything else. The API keeps the two apart: title is the heading's text, and content is the body, everything after the heading. Writing title changes only the heading's text; writing markdown or html changes only the body.

• A title is one line: runs of spaces and line breaks become single spaces, and it can be up to 1,000 characters. An empty title makes the note Untitled.
• Creating a note without title: a body that opens with a level-1 heading (# Saturday 24 October) uses it as the title. Otherwise the note is Untitled.
• Changing the title rewrites the heading's text and drops any formatting or icon inside it. Sending a note's title back unchanged changes nothing: titles are compared with their whitespace collapsed, as a write collapses it, so one with a double space is left as it was too.
• preview is the start of the text after the title, up to 120 characters, as the note list shows it.
• url is the note's address on the web, https://open.blancnote.app/n/<id>, for showing and sharing; it lands on a page at open.blancnote.app that sends the browser on to the note's blanc://note/<id> link. appUrl is that link itself, for native apps that would rather skip the browser.

All of this assumes the note opens with a level-1 heading, as every note made in Blanc does. If the person has turned the first line into something else, such as a paragraph or a smaller heading, there's no title heading to keep apart: title is still that first line's text, but content.html starts with it, writing the body replaces it (and so changes the title), and writing title adds a new heading above it.

Reading: HTML, Markdown and plain text

GET /v1/notes/{id} returns the note with content.html. Add format for other renderings:

curl "https://api.blancnote.app/v1/notes/note-1792588456123-k3x9?format=markdown,text" \
  -H "Authorization: Bearer $TOKEN"

• content.html is the body exactly as Blanc stores it, Blanc's data- attributes and all. Write it back unchanged and nothing is lost, live blocks included, unless its text has a tab or a line break outside a code block (from a pasted spreadsheet, say). Then it counts as HTML formatted for reading, and its whitespace collapses (see what happens to HTML).
• content.markdown and content.text are the renderings Blanc's own exports make, for showing a note in an app that doesn't render HTML.
• Every write returns the note as well, and takes format the same way.

Writing: send Markdown

Send Markdown unless you know why you need HTML. Plain text is Markdown. Blanc reads GitHub-flavoured Markdown: headings, emphasis, links (bare URLs too), lists, quotes, code, tables, strikethrough and horizontal rules.

• A single line break doesn't start a new line. Milk and Eggs on two lines become one paragraph, Milk Eggs. Leave a blank line between paragraphs, end a line with two spaces or a backslash for a break within one, or send the lines as a list (- Milk).
• Task lists become Blanc checklists. - [ ] Milk is an unticked item and - [x] Eggs a ticked one. A list converts only when every item in it is a task; a list that mixes tasks and bullets stays a bulleted list, and a numbered task list (1. [ ] Milk) stays numbered.
• Images can be web addresses or data: URLs. Inline images count toward the 10 MB limit on a note write.

Everything you send is cleaned before it's stored, by the rules below, whether it arrived as Markdown or as HTML.

What happens to HTML

Blanc keeps what its editor can show and drops anything that could run code.

• Kept: paragraphs, headings, lists and checklists, block quotes, code blocks and inline code, horizontal rules, line breaks, tables and their column groups, figures and captions, links and images; bold, italic, underline, strikethrough, highlight (mark), subscript and superscript; div, span and label; checkboxes, the only inputs a note has; and the attributes Blanc's own content is made of: class, style, every data- attribute, and the media attributes Blanc's editor writes (src, name, size, mime, url, provider, videoid, displaymode, attachmentid).
• Removed, with what's inside them: scripts, style sheets, iframes, objects and embeds, SVG and MathML, and form fields such as text areas and menus.
• Removed, keeping their text: every other element, such as section, form or button.
• Removed attributes: event handlers such as onclick; links in any scheme but http, https, mailto, tel and Blanc's own blanc and blanc-note (the link's text stays); a style that loads or runs something (url(, expression(, @import, or a backslash); a video's url unless it's http or https, and its provider unless Blanc knows it.
• Images and files load only from http, https or data: addresses. A data: URL or a file's mime that a browser would run, such as HTML, SVG, XML or script, becomes application/octet-stream.
• Whitespace is kept exactly as you send it, double spaces included, unless the HTML has line breaks or tabs in its text outside pre. That's HTML formatted for reading, and its whitespace collapses as a browser would show it.
• Loose text outside any element becomes a paragraph.

Live blocks

A Blanc note can hold a live Todoist list. Its tasks come from Todoist on the person's devices and aren't stored in the note, so the API can't show them. Instead:

• content.html has the block's wrapper, <div data-todoist-project-block …>, with its attributes, so writing that HTML back keeps the live list.
• content.markdown has <!-- blanc: live Todoist block --> where the list sits.
• content.text has [Live Todoist list: <project name>], or [Live Todoist list] when it has no name.

The markers are placeholders. Writing the Markdown or text back replaces the live list with nothing, or with a line of text. To edit a note that has one, write html, or use append, which leaves the rest of the note as it was.

An Index block, a live list of notes by tag, notebook or smart folder, is stored with its latest results, so it reads as a bulleted list of those notes' titles, linked to them in HTML and Markdown.

Adding to a note

POST /v1/notes/{id}/append adds blocks after the note's last block that has something in it. With heading, they go at the end of the section under the first level-2 heading that reads the same, ignoring case and extra spaces; a section runs to the next level-1 or level-2 heading. Only headings in the note's main flow count, not one nested inside another block. If there's no such heading, Blanc adds it at the end of the note, with the blocks under it.

curl -X POST https://api.blancnote.app/v1/notes/note-1792588456123-k3x9/append \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a90-5c1e-4c5f-9a8e-0d3b2f7c4e11" \
  -d '{ "markdown": "- 09:41 Called Amy about Saturday", "heading": "Log" }'

Append is the safest way to add to a note. It reads the note and writes it back in one step, so it builds on the latest version Blanc has rather than on a copy your app read earlier, and two appends never lose each other's blocks. It can't protect against an edit on one of the person's devices at the same moment, though: Blanc saves a note whole, and the newer save wins. An app keeping a daily log can create the note once, keep its id, and append through the day. If it loses the id, GET /v1/notes?title=… finds the note by its exact title.

Editing safely with If-Match

PATCH /v1/notes/{id} replaces the whole body. If the person changed the note after you read it, a patch without a condition wins, just as an edit from another of their devices would. The version Blanc keeps means nothing is lost, but they'd have to go looking for it.

So send the ETag of the note you read as If-Match:

curl -X PATCH https://api.blancnote.app/v1/notes/note-1792588456123-k3x9 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "2026-10-23T08:02:51.456Z"' \
  -d '{ "markdown": "## Morning\n\nWalked to the river before work." }'

The ETag is the note's updatedAt in quotes; the bare timestamp works too, and * means "as long as the note exists". Send one value: a weak (W/…) tag or a list is a 400. If the note has changed, nothing is written and the answer is 412 precondition_failed, with the note's currentUpdatedAt, even when the note is now in the trash. Read it again, apply your change to what's there now, and try again. A patch that changes nothing writes nothing.

Retrying safely with Idempotency-Key

Networks fail after a write lands, and a retry shouldn't make a second note or add a line twice. Send an Idempotency-Key on create and append: any 1 to 255 visible ASCII characters you make up for that one operation, such as a UUID from your queue. Retry with the same key and exactly the same body.

• For 24 hours, a request with a key your app already used for this person writes nothing. It answers with the first request's status, the note as it is now, and Idempotent-Replayed: true.
• Only requests that succeeded count, so a request that failed can be retried with its key.
• The same key with a different request is 422 idempotency_key_reused. The same request means the same method, path and JSON body: the same fields with the same values, in the same order. Spacing doesn't matter, and the query string isn't part of it.
• A key belongs to your app and this person, whatever the endpoint or the note, so use a fresh one for every operation.
• If the note it made has since been deleted for good, a replay answers 404.

Trash, versions and locked notes

• Trash. DELETE /v1/notes/{id} moves a note to the trash, as if the person had deleted it, and clears its pins. The trash empties after 30 days, the next time one of the person's devices opens Blanc; until then POST /v1/notes/{id}/restore brings the note back to its notebooks and tags, unpinned. Notes in the trash can be read, but writing to one answers 409 in_trash: restore it first. The API can't delete a note for good.
• Versions. Before a patch changes a note's title or body, Blanc keeps a version labelled Before ‹your app› edited it. Before an append it keeps one labelled Before ‹your app› added to it, at most once every ten minutes for each note, and none for a note over 1 MB. They appear in the note's history, where the person can restore them. Each device keeps the newest 15 versions apps made for a note apart from the person's own, so your app's versions never push out the history the person made; an app that edits one note many times pushes out only its own older versions. Changing a note's notebooks, tags or pin keeps no version. The API can't read or change versions.
• Locked notes. Blanc doesn't lock notes yet. When it does, a locked note will list with locked: true, an empty preview and content: null, and every write to it will answer 409 locked. No scope unlocks a note. When a write comes back locked, hold your change and tell the person the note is locked in Blanc; don't make a second, unlocked copy beside it.

Notebooks and tags

GET /v1/notebooks and GET /v1/tags each return the whole list in one page. Notebooks come flat, sorted so that the notebooks inside any one parent are in the sidebar's order; rebuild the tree from parentId. Tags come in the sidebar's order. Both carry archived: things the person put away, which a picker would usually hide.

To file a note, send notebookIds and tags on create or patch; each replaces the note's whole set. A note's notebookIds and tags leave out notebooks and tags in the trash, as Blanc does, so you can send back what you read.

• Notebooks must exist, archived ones included. An unknown id is a 404 that names it. Apps file notes into the person's notebooks; they don't make them.
• Tags are made as needed, as typing a new tag in Blanc does. Names are stored trimmed, in lower case, with spaces as hyphens: Daily Notes becomes daily-notes. Naming a tag the person deleted brings it back.
• Apps can't create, rename or delete notebooks, or rename or delete tags.

Polling for changes

There are no webhooks in v1. Instead, GET /v1/notes?since=… is a feed of the notes that changed, made for polling from a server or a device.

1. Start from the beginning to copy everything and then keep up: GET /v1/notes?since=1970-01-01T00:00:00Z returns every note, trashed ones included, and a note that changes while you page through comes again later, so nothing slips between your copy and the feed. Or start from a time of your choosing, from before you begin any copy of your own, and a little early: since is compared with Blanc's clock, not yours, and a time in Blanc's future returns empty pages until it arrives. Write a + in an offset as %2B.
2. Read every page. While hasMore is true, ask again with cursor set to nextCursor, and nothing else but limit.
3. Keep the last nextCursor. It's never null in a feed. Poll with it later: GET /v1/notes?cursor=….

The feed returns note summaries, the oldest change first, including your own app's writes. A note that moved to or from the trash comes as a summary with deletedAt set or cleared. A note deleted for good comes as { "id": …, "purged": true, "purgedAt": … }, so your copy never outlives it; one emptied from the trash arrives when one of the person's devices opens Blanc after its 30 days. Summaries have no body: read the note for that. A feed takes no filters, because it reports every note that changes; filter the items yourself.

What the feed doesn't show. A note appears when the note itself changes. Deleting a notebook or tag for good, or renaming a tag on a device, changes the notebookIds or tags of the notes involved without those notes appearing, so read the notebook and tag lists again when you need them current.

// Returns the cursor to poll with next time.
async function poll(cursor, since) {
  let query = cursor ? `cursor=${encodeURIComponent(cursor)}` : `since=${encodeURIComponent(since)}`;
  for (;;) {
    const page = await (await blanc(`/v1/notes?${query}&limit=100`)).json();
    for (const item of page.data) {
      if (item.purged) forget(item.id);
      else remember(item); // a summary; deletedAt says whether it's in the trash
    }
    if (!page.hasMore) return page.nextCursor;
    query = `cursor=${encodeURIComponent(page.nextCursor)}`;
  }
}

The feed runs a second or more behind. It reads only up to the start of the oldest database transaction still open, anyone's, less a second, and never more than about five minutes back. That way it doesn't hand out a cursor past a change that hasn't finished saving; only a write still saving after five minutes could be passed. In practice a change appears a second or two after it's made, and later only while a long transaction is still running. A change your app just made may come on the next poll rather than this one. When nothing has settled since your cursor, you get an empty page and a cursor to keep.

Poll as often as your app needs, within the rate limits: every few minutes is plenty for most.

Rate limits

Reads are GET /v1/me and the GET calls on notes, notebooks and tags. Writes are creating, editing, appending to, trashing and restoring notes. Every request with a valid token counts, whatever its answer, errors included; a request without one isn't counted, and neither are the OAuth endpoints or the OpenAPI document. Over a limit, the answer is 429 rate_limited: wait the number of seconds in Retry-After, then try again. Responses also carry RateLimit and RateLimit-Policy headers in the format of the IETF's draft standard, with an entry for each limit the request counts against (reads-per-user and reads-per-app, or the same for writes), so your app can pace itself before it's refused.

A note write's body can be up to 10 MB, and a form post to the OAuth endpoints up to 16 KB.

Errors

Every error from a resource endpoint has the same shape. Switch on error, which never changes; message is for people reading logs, and its wording can.

{ "error": "in_trash", "message": "The note is in the trash. Restore it, then write to it." }

• A 401 carries WWW-Authenticate: Bearer realm="blanc", error="invalid_token", or just Bearer realm="blanc" when no token was sent or the Authorization header isn't Bearer <token> (RFC 6750). Refresh the token; if the refresh says invalid_grant, the person has to connect again. A token also stops working when the person connects your app again with fewer scopes, or when Blanc turns the app off.
• A 403 carries error="insufficient_scope" and the scope the call needs.
• A 412 adds currentUpdatedAt, the note's updatedAt now.
• An address the API doesn't have is 404 not_found.

Errors from the OAuth endpoints use RFC 6749's shape instead; see when connecting fails.

Versions and deprecation

This is version 1, and everything lives under /v1.

• Adding a field or an optional parameter isn't a breaking change, and needs no notice. Write your app to ignore fields it doesn't know.
• Breaking changes, such as removing or renaming a field or changing its type, ship as /v2. /v1 keeps working for 12 months after /v2 arrives.

Limits

Lengths count UTF-16 code units, as JavaScript's length does: most characters count as one, and an emoji as two.

Not in v1

• Webhooks. Poll the changes feed.
• Calls from a web page. Apart from the OpenAPI document, /v1 doesn't let pages on other sites read its responses, so a browser can't call it directly. Call it from your server.
• Full-text search. q matches titles only.
• Attachments. There's no upload; images travel in the body as addresses or data: URLs.
• Archiving and pins inside notebooks. archived is read-only, and pinned is the pin that tops every list.
• Version history, permanent deletion, and changing notebooks or tags other than filing a note in them.

Reference

Generated from the OpenAPI document.

OAuth

Connecting your app to a user's Blanc account, and disconnecting it.

Identity

Who a token acts for.

Notes

The notes themselves: list, read, create, edit, add to, trash and restore. The API can't delete a note for good.

Filing

The user's notebooks and tags, read-only, for filing notes and for pickers.

Meta

This document.

Objects

{
  "id": "note-1792588456123-k3x9",
  "title": "Saturday 24 October",
  "url": "https://open.blancnote.app/n/note-1792588456123-k3x9",
  "appUrl": "blanc://note/note-1792588456123-k3x9",
  "notebookIds": [
    "nb-journal"
  ],
  "tags": [
    "daily"
  ],
  "pinned": false,
  "archived": false,
  "deletedAt": null,
  "locked": false,
  "preview": "Morning Walked to the river before work.",
  "createdAt": "2026-10-21T13:14:16.123Z",
  "updatedAt": "2026-10-23T08:02:51.456Z",
  "content": {
    "html": "<h2>Morning</h2><p>Walked to the river before work.</p>",
    "markdown": "## Morning\n\nWalked to the river before work.\n"
  }
}

{
  "id": "nb-journal",
  "name": "Journal",
  "parentId": null,
  "archived": false,
  "noteCount": 214
}

{
  "name": "daily",
  "color": "#085C51",
  "archived": false
}

{
  "userId": "LXEWQrcmsEQBYnyp-6wy9chTD7GQPMTbAiWHF5IaSIE",
  "app": {
    "clientId": "blanc_Xq3vN8rTkL2pW9yZb4cD1e",
    "name": "Morning"
  },
  "scopes": [
    "notes:write",
    "offline"
  ]
}

{
  "title": "Saturday 24 October",
  "markdown": "## Morning\n\nWalked to the river before work.",
  "notebookIds": [
    "nb-journal"
  ],
  "tags": [
    "daily"
  ]
}

{
  "markdown": "- 09:41 Called Amy about Saturday",
  "heading": "Log"
}

{
  "error": "in_trash",
  "message": "The note is in the trash. Restore it, then write to it."
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "3c9f0d2a8b7e61f4a05d9c2e.…",
  "scope": "notes:read notes:write offline"
}

{
  "error": "invalid_grant",
  "error_description": "The refresh token has expired."
}

Help

Questions, problems and verification requests: api@blancnote.app.