마크다운 API 시작하기

API 토큰 하나로 스크립트나 AI 에이전트가 노트를 마크다운으로 읽고, 새로 만들고, 끝에 덧붙입니다.

이용 조건 웹 · Mac · iPhone 앱에서 토큰 발급 · 계정 비밀번호 필요

CommonNote의 공개 API는 노트를 마크다운으로 주고받습니다. 할 수 있는 일은 네 가지입니다: 노트 목록 보기, 노트를 마크다운으로 읽기, 새 노트 만들기, 기존 노트 끝에 덧붙이기. 노트를 통째로 덮어쓰거나 지우는 길은 일부러 두지 않았습니다. 함께 쓰는 문서를 한 번에 갈아엎는 일은 편집기에서 사람이 하도록 했습니다.

토큰 만들기

상단 바 오른쪽 프로필(아바타)을 누르고 계정 보안을 엽니다.
API 토큰 칸에서 토큰 이름(예: 맥북 Claude Code)과 지금 쓰는 비밀번호를 적습니다.
토큰 만들기를 누르고, 나온 토큰(cnk_로 시작)을 바로 복사해 안전한 곳에 둡니다. 다시 볼 수 없습니다.

토큰은 만료가 없습니다. 안 쓰는 토큰은 목록에서 폐기하세요. 목록에는 마지막 사용 시각이 나옵니다.
계정당 20개까지 만들 수 있습니다.
토큰은 /api/v1에만 통합니다. 다른 경로에 쓰면 401이 돌아옵니다.
사용법 단추를 누르면 앱 안에서 curl 예시를 볼 수 있습니다.

토큰은 비밀번호처럼 다루세요. 코드 저장소, 채팅, 공유 문서에 붙여 넣지 마세요. 새어 나갔다고 생각되면 곧바로 폐기하고 새로 만드세요.

엔드포인트

기준 주소는 https://commonnote.app/api/v1이고, 모든 요청에 Authorization: Bearer cnk_… 헤더를 붙입니다.

요청	하는 일
`GET /notes?limit=50&q=`	내가 소유했거나 나에게 직접 공유된 노트 목록, 최근 수정 순. 공유 노트북·팀 프로젝트를 통해서만 볼 수 있는 노트는 목록에 없지만, id를 알면 `GET /notes/:id`로 읽을 수 있습니다. `limit` 기본 50·최대 200. `q`는 제목만 부분 검색합니다. 휴지통·템플릿은 빠집니다. 항목마다 `id`, `title`, `notebookId`, `role`(owner/editor/viewer), `locked`, `createdAt`, `updatedAt`.
`GET /notes/:id`	`Accept: text/markdown`이면 마크다운 본문만, 아니면 JSON(`id`, `title`, `notebookId`, `role`, `createdAt`, `updatedAt`, `markdown`). 이미지 주소는 `https://commonnote.app/…` 절대 주소로 바뀝니다.
`POST /notes`	본문 `{ "title"?, "markdown", "notebookId"? }`로 새 노트를 만듭니다. 201과 `{ id, title, url }`이 돌아옵니다. 제목을 빼면 마크다운 첫 제목을 씁니다. `notebookId`는 내가 소유한 노트북만 됩니다.
`POST /notes/:id/append`	본문 `{ "markdown" }`을 노트 끝에 덧붙입니다. `{ ok, id, appendedBlocks }`가 돌아옵니다. 보기 권한만 있으면 403.

GET /api/v1/에 토큰을 붙여 부르면 엔드포인트 목록과 속도 제한을 JSON으로 알려 줍니다.

해 보기

토큰은 명령에 직접 적지 말고 환경 변수에 넣어 쓰세요.

export COMMONNOTE_TOKEN="cnk_…"   # 셸 설정 파일에 넣어 두면 편합니다

# 최근 노트 5개
curl -H "Authorization: Bearer $COMMONNOTE_TOKEN" \
  "https://commonnote.app/api/v1/notes?limit=5"

# 노트 하나를 마크다운으로
curl -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Accept: text/markdown" \
  https://commonnote.app/api/v1/notes/<노트-id>

# 새 노트
curl -X POST -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"오늘 결과","markdown":"# 오늘 결과\n- OD600 0.43"}' \
  https://commonnote.app/api/v1/notes

# 노트 끝에 덧붙이기
curl -X POST -H "Authorization: Bearer $COMMONNOTE_TOKEN" -H "Content-Type: application/json" \
  -d '{"markdown":"## 후속\n- 내일 재측정"}' \
  https://commonnote.app/api/v1/notes/<노트-id>/append

노트 id는 목록 응답의 id나, 노트 목록에서 우클릭 → 공유 링크 복사로 얻은 주소의 ?note= 뒤에 있습니다.

한도와 오류

상황	응답
토큰 하나로 1분에 300회 넘게 요청	429와 `Retry-After` 헤더(초). 그만큼 기다렸다가 다시 보내세요.
markdown이 비었거나 2MB(2,000,000바이트)를 넘음	400
노트가 없음(휴지통으로 간 노트 포함)	404
접근 권한 없음, 보기 전용 노트에 덧붙이기, 내 노트북이 아님	403
비밀번호로 잠긴 노트·노트북	423. 웹이나 앱에서 잠금을 풀어 두었더라도 API 토큰으로는 읽거나 덧붙일 수 없습니다. 브라우저·앱에서 푼 잠금은 토큰에 적용되지 않습니다.

노트 제목은 결국 본문의 글이 있는 첫 줄(최대 200자)로 정해집니다. title은 만들 때 잠깐 쓰일 뿐 본문이 저장되면 첫 줄로 바뀌므로, 원하는 제목을 마크다운 첫 줄(예: # 제목)로 넣으세요. 스크립트와 AI 도구에 붙이는 예시는 스크립트·AI 도구와 연결하기에 있습니다.