Get started with the Markdown API

With one API token, scripts and AI agents can read your notes as Markdown, create new ones and append to existing ones.

Applies to Create tokens on the web, Mac or iPhone app · requires your account password

The CommonNote public API speaks Markdown. It does four things: list notes, read a note as Markdown, create a note and append to the end of an existing note. There is deliberately no way to overwrite or delete a note — rewriting a shared document wholesale is left to people in the editor.

Create a token

Click your profile (avatar) at the right end of the top bar and open Account security.
In the API tokens section, enter a token name (for example, MacBook Claude Code) and your Current password.
Click Create token, then copy the token (it starts with cnk_) right away and store it somewhere safe. It won’t be shown again.

Tokens never expire. Revoke any you stop using; the list shows when each was last used.
You can have up to 20 tokens per account.
Tokens work only on /api/v1. Using one anywhere else returns 401.
Click How to use to see curl examples inside the app.

Treat a token like a password. Don’t paste it into code repositories, chats or shared documents. If you think one has leaked, revoke it immediately and create a new one.

Endpoints

The base URL is https://commonnote.app/api/v1. Send an Authorization: Bearer cnk_… header with every request.

Request	What it does
`GET /notes?limit=50&q=`	Notes you own or that were shared with you directly, most recently updated first. Notes you can reach only through a shared notebook or team project are not listed, but you can still read them by id with `GET /notes/:id`. `limit` defaults to 50, maximum 200. `q` matches titles only. Trash and templates are excluded. Each item has `id`, `title`, `notebookId`, `role` (owner/editor/viewer), `locked`, `createdAt` and `updatedAt`.
`GET /notes/:id`	With `Accept: text/markdown`, just the Markdown body; otherwise JSON (`id`, `title`, `notebookId`, `role`, `createdAt`, `updatedAt`, `markdown`). Image paths become absolute `https://commonnote.app/…` URLs.
`POST /notes`	Creates a note from `{ "title"?, "markdown", "notebookId"? }` and returns 201 with `{ id, title, url }`. Without a title, the first Markdown heading is used. `notebookId` must be a notebook you own.
`POST /notes/:id/append`	Appends `{ "markdown" }` to the end of the note and returns `{ ok, id, appendedBlocks }`. Returns 403 if you only have view access.

Calling GET /api/v1/ with your token returns the endpoint list and rate limit as JSON.

Try it

Keep the token in an environment variable instead of typing it into commands.

export COMMONNOTE_TOKEN="cnk_…"   # add this to your shell profile

# Five most recent notes
curl -H "Authorization: Bearer $COMMONNOTE_TOKEN" \
  "https://commonnote.app/api/v1/notes?limit=5"

# One note as Markdown
curl -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Accept: text/markdown" \
  https://commonnote.app/api/v1/notes/<note-id>

# New note
curl -X POST -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Today’s results","markdown":"# Today’s results\n- OD600 0.43"}' \
  https://commonnote.app/api/v1/notes

# Append to a note
curl -X POST -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Content-Type: application/json" \
  -d '{"markdown":"## Follow-up\n- Re-measure tomorrow"}' \
  https://commonnote.app/api/v1/notes/<note-id>/append

Find a note’s id in the id field of the list response, or right-click a note in the note list, choose Copy share link and take the part after ?note=.

Limits and errors

Situation	Response
More than 300 requests per minute with one token	429 with a `Retry-After` header (seconds). Wait that long and retry.
Empty markdown, or more than 2 MB (2,000,000 bytes)	400
No such note (including notes in the Trash)	404
No access, appending to a view-only note, or not your notebook	403
Password-locked note or notebook	423. API tokens can’t read or append to password-locked notes, even while the note is unlocked in the web or app. Unlocking in a browser or the app doesn’t apply to tokens.

A note’s title ends up being the first line of the body that has text (up to 200 characters). title is only used briefly on creation and is replaced by that first line once the body is saved, so put the title you want as the Markdown’s first line (e.g. # Title). For script and AI tool examples, see Connect scripts and AI tools.