Notion API 페이지 속성 업데이트

Notion 페이지의 속성(properties), 아이콘(icon), 커버(cover) 등을 수정할 때 쓰는 API예요. PATCH /v1/pages/{page_id} 엔드포인트를 호출해서 페이지의 여러 속성을 한 번에 갱신할 수 있어요. 공식 문서의 내용을 쉽게 풀어 설명할게요.

출처: 문서

본문

이 API가 하는 일

PATCH 요청을 보내면 페이지의 속성 값, 아이콘, 커버 이미지, 잠금 상태, 템플릿 적용, 내용 삭제, 휴지통 이동 등을 바꿀 수 있어요. 요청이 성공하면 갱신된 페이지 객체(page object)를 반환해요.

요청 본문(body)에는 다음과 같은 항목을 담을 수 있어요.

properties : 페이지 속성 값. 페이지의 부모가 데이터 소스(데이터베이스)일 때만 사용할 수 있어요 (데이터 소스 밖에 있는 페이지의 title만 바꾸는 경우는 예외).
icon / cover : 페이지 아이콘·커버 이미지 설정.
is_locked : 앱 UI에서 페이지가 편집되지 않도록 잠글지 여부. 참고로 이 설정은 API를 통한 업데이트에는 영향을 주지 않아요.
template : 기존 페이지에 템플릿 적용.
erase_content : 페이지의 모든 블록 자식(block children)을 삭제.
in_trash / is_archived : 페이지를 휴지통에 넣거나 보관 처리.

기본 호출 예시 (curl)

curl로 직접 호출할 때는 아래처럼 PATCH 메서드와 헤더를 지정해요.

curl --request PATCH \
  --url https://api.notion.com/v1/pages/{page_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '{
    "properties": {}
  }'

헤더로는 Authorization(Bearer 토큰), Content-Type: application/json, 그리고 필수인 Notion-Version(예: 2026-03-11)을 함께 보내야 해요.

TypeScript SDK 예시

공식 SDK를 쓰면 더 간단해요. 아래 예시는 Name 속성(제목)을 바꾸는 코드예요.

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.pages.update({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  properties: {
    Name: {
      title: [{ text: { content: "Updated Title" } }]
    }
  }
})

속성 타입별 값 업데이트

properties 객체 안에서 속성 이름을 키로, 해당 타입에 맞는 값을 넣어요. 대표적인 타입 예시는 다음과 같아요.

text / title (일반 텍스트, 제목)

{
  "properties": {
    "설명": {
      "rich_text": [{ "text": { "content": "새 내용" } }]
    }
  }
}

number (숫자)

{
  "properties": {
    "가격": { "number": 12000 }
  }
}

select (단일 선택)

{
  "properties": {
    "상태": { "select": { "name": "진행 중" } }
  }
}

multi_select (다중 선택)

{
  "properties": {
    "태그": { "multi_select": [{ "name": "API" }, { "name": "한국어" }] }
  }
}

date (날짜)

{
  "properties": {
    "마감일": { "date": { "start": "2026-12-31" } }
  }
}

checkbox (체크박스)

{
  "properties": {
    "완료": { "checkbox": true }
  }
}

그 밖에도 URL, 이메일, 전화번호, 사람(people), 관계(relation), 공식(formula) 등의 타입을 지원해요. 참고로 rollup 속성 값은 업데이트할 수 없고, 페이지의 부모(parent)도 변경할 수 없어요.

사용 시 유의사항

권한 : 이 엔드포인트를 호출하려면 연결(connection)에 대상 페이지에 대한 update content 권한이 있어야 해요. 권한이 없다면 403 HTTP 응답을 받아요. Developer portal에서 연결을 선택하고 Configuration 탭의 Capabilities 섹션에서 권한을 확인·수정할 수 있어요.
내용 추가 : 페이지에 새 내용(블록)을 추가하려면 이 API가 아니라 append block children API를 사용해요. 이때 페이지의 page_id를 block_id로 넘기면 돼요.
템플릿 적용 : template 본문 파라미터로 기존 페이지에 템플릿을 적용할 수 있어요. 부모 데이터 소스의 기본 템플릿(type=default)이나 특정 템플릿(type=template_id)을 지정할 수 있고, template[timezone]으로 @now·@today 같은 템플릿 변수 해석에 쓰일 IANA 타임존을 정할 수 있어요. 생략하면 공개 연결·개인 액세스 토큰에서는 연결된 사용자의 타임존을, 내부 연결에서는 UTC를 사용해요.
내용 삭제 : erase_content 플래그는 페이지의 모든 블록 자식을 삭제하는 파괴적인(destructive) 작업이라 되돌릴 수 없어요. 주로 기존 내용을 비우고 템플릿 내용으로 대체할 때 써요.
오류 처리 : 각 엔드포인트는 여러 오류 코드를 반환할 수 있어요. 대표적으로 400(잘못된 JSON), 401(인증 실패), 403(권한 없음), 404(객체 없음), 409(충돌), 429(요청 제한) 등이 있어요. 자세한 내용은 Status codes 문서를 확인해요.

더 알아보기 (Learn more)

공식 문서