스크립트·AI 도구와 연결하기

환경 변수에 넣은 API 토큰으로 스크립트와 AI 에이전트가 노트를 읽고, 만들고, 덧붙이게 합니다.

이용 조건 API 토큰 필요 · macOS·Linux 셸, Python 3

이 글은 마크다운 API의 네 가지 요청만으로 할 수 있는 흔한 일들을 모았습니다. 목록 보기, 마크다운으로 읽기, 새 노트 만들기, 노트 끝에 덧붙이기 외의 동작(덮어쓰기·삭제·본문 검색 등)은 API에 없습니다.

토큰을 안전하게 두기

프로필 메뉴 → 계정 보안 → API 토큰에서 용도별로 토큰을 만듭니다(예: “실험 기록 스크립트”, “맥북 Claude Code”). 하나가 새어도 그것만 폐기하면 됩니다.
토큰을 셸 설정 파일(~/.zshrc 등)에 환경 변수로 넣습니다: export COMMONNOTE_TOKEN="cnk_…"
스크립트와 도구는 이 변수를 읽게 합니다. 코드 파일에 토큰을 직접 적지 않습니다.

토큰은 만료되지 않습니다. 다 쓴 토큰, 오래 쓰지 않은 토큰(목록의 “마지막 사용”으로 확인)은 폐기하세요. 토큰을 채팅창이나 AI 대화에 붙여 넣지 마세요.

셸: 노트 끝에 한 줄 덧붙이기

측정 결과나 작업 로그를 정해 둔 노트 한 곳에 쌓을 때 씁니다. 줄바꿈과 따옴표가 안전하도록 JSON은 python3로 만듭니다.

NOTE_ID="<노트-id>"
LINE="- $(date '+%Y-%m-%d %H:%M') 원심분리 끝, 상층액 보관"

python3 -c 'import json,sys; print(json.dumps({"markdown": sys.argv[1]}))' "$LINE" |
curl -sS -X POST -H "Authorization: Bearer $COMMONNOTE_TOKEN" \
  -H "Content-Type: application/json" --data-binary @- \
  "https://commonnote.app/api/v1/notes/$NOTE_ID/append"

파이썬: 파일을 노트로 올리고, 노트를 파일로 받기

표준 라이브러리만 씁니다.

import json, os, pathlib, urllib.parse, urllib.request

BASE = "https://commonnote.app/api/v1"
TOKEN = os.environ["COMMONNOTE_TOKEN"]

def call(method, path, body=None, accept="application/json"):
    req = urllib.request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {TOKEN}",
                 "Content-Type": "application/json", "Accept": accept})
    with urllib.request.urlopen(req) as res:
        text = res.read().decode()
        return json.loads(text) if accept == "application/json" else text

# 1) 마크다운 파일을 새 노트로
md = pathlib.Path("report.md").read_text(encoding="utf-8")
created = call("POST", "/notes", {"markdown": md})
print(created["url"])

# 2) 제목에 '주간'이 든 최근 노트를 파일로 저장
for note in call("GET", "/notes?limit=20&q=" + urllib.parse.quote("주간"))["notes"]:
    if note["locked"]:
        continue
    body = call("GET", f"/notes/{note['id']}", accept="text/markdown")
    pathlib.Path(f"{note['id']}.md").write_text(body, encoding="utf-8")

429가 오면 Retry-After 헤더의 초만큼 기다렸다가 다시 보내세요. 토큰 하나당 1분에 300회까지입니다.
비밀번호로 잠긴 노트는 앱에서 잠금을 풀어 두었더라도 API 토큰에는 늘 423이 돌아오므로 위 예시처럼 건너뜁니다.
한 번에 보내는 markdown은 2MB 이하여야 합니다.

AI 코딩 에이전트(Claude Code 등)에 맡기기

Claude Code처럼 터미널에서 명령을 실행하는 에이전트는 이 API를 그대로 쓸 수 있습니다. 토큰은 에이전트가 실행되는 셸의 환경 변수로만 넘기고, 대화에는 변수 이름만 알려 주세요.

에이전트를 실행할 터미널에서 COMMONNOTE_TOKEN이 설정돼 있는지 확인합니다(값을 화면에 찍지 말고 test -n "$COMMONNOTE_TOKEN" && echo set 정도로).
에이전트에게 이렇게 요청합니다: CommonNote 마크다운 API(https://commonnote.app/api/v1)를 써 줘. 토큰은 환경 변수 COMMONNOTE_TOKEN에 있으니 Authorization: Bearer 헤더로 쓰고, 토큰 값을 출력하거나 파일에 적지 마. 제목에 '회의'가 들어간 최근 노트를 마크다운으로 읽어서 할 일만 뽑아 줘.
결과를 남기게 하려면 “새 노트로 만들어 줘”(POST /notes)나 “노트 <id> 끝에 덧붙여 줘”(/append)라고 덧붙입니다.

에이전트가 쓸 수 있는 것은 내 계정이 볼 수 있는 노트 전부입니다. 에이전트 전용 토큰을 따로 만들고, 작업이 끝나면 폐기하는 습관을 들이세요. API에는 삭제·덮어쓰기가 없으므로 에이전트가 노트를 지우거나 통째로 바꿀 수는 없습니다.