공식 Notion API 레퍼런스는 페이지, 데이터베이스, 블록, 댓글, 사용자, 검색, 웹후크(Webhooks) 및 파일 업로드에 대한 작동 방식을 설명합니다. 기능 개요에는 AI 엔드포인트(AI-endpoint), autofill 엔드포인트, AI 블록 또는 Q&A 요청에 대한 내용이 단 하나도 없습니다. 이는 문서 읽기의 누락이 아니라 2026-07-18 기준의 사실입니다. 이 사실은 Notion AI를 중심으로 어떤 자동화를 구축할 수 있고, 어떤 것을 구축할 수 없는지를 결정합니다.

여기서 논지는 좁고 검증 가능합니다: 만약 특정 내장 AI 동작이 API에 문서화되어 있지 않다면, 이를 워크플로우(Workflow)의 기반으로 삼아서는 안 됩니다. /AI 슬래시 명령어(/slash command)나 Autofill을 중심으로 자동화를 설계한 개발자는 코드 리뷰 단계가 아니라, 통합 토큰(Integration token)이 존재하지 않는 엔드포인트에 부딪히는 프로덕션(Prod) 환경에서 이 사실을 깨닫게 될 것입니다.

다음 순서로 진행하겠습니다: 통합 토큰이 물리적으로 허용하는 것, 왜 내장된 Notion AI가 다른 메커니즘으로 작동하는지, 원하는 동작과 사용 가능한 API 간의 매핑 맵, 그리고 Notion이 별도의 AI 레이어를 위해 무엇을 제안하는지에 대해 다룹니다. 앞서 언급한 별도의 레이어를 위해서는 모델에 대한 호환 가능한 API 액세스가 유용하겠지만, 이는 Notion AI의 대체가 아닌 두 번째 고려 사항입니다.

문서화된 API가 통합 토큰에 허용하는 것

토큰은 정해진 경로를 통해 생성됩니다: Settings → Connections → 새로운 내부 또는 공개(OAuth) 연결. 통합 생성에 관한 공식 페이지에는 AI 권한을 부여하거나 설명하는 항목이 단 하나도 포함되어 있지 않습니다. 설정 시 사용할 수 있는 유일한 제어 수단은 콘텐츠, 댓글 및 사용자에 대한 액세스 권한(Capabilities)뿐입니다.

전체 capabilities 분류(taxonomy of capabilities)는 다음과 같습니다: 콘텐츠 읽기(Read content), 콘텐츠 업데이트(Update content), 콘텐츠 삽입(Insert content), 댓글 읽기(Read comments), 댓글 삽입(Insert comments), 그리고 사용자 정보에 대한 세 가지 수준의 액세스 권한입니다. 이 목록에는 "AI" 카테고리가 전혀 없으며, 이는 실수가 아닙니다. 바로 이 capabilities가 토큰이 수행할 수 있는 작업을 물리적으로 제한합니다. 만약 특정 동작이 이 권한 그리드에 없다면, 그것은 우연이 아니라 구조적으로 통합(integration)에서 사용할 수 없도록 설계된 것입니다.

프로젝트 시작 시 유용한 습관은: 원하는 모든 동작을 일상적인 언어로 적어본 뒤, 그것이 어떤 capability에 속하는지 질문하는 것입니다. "페이지 요약 생성"은 콘텐츠에 대한 작업이 아니라 모델 호출(model call)이기 때문에, Read, Update, Insert content 중 어디에도 해당하지 않습니다. 즉, 토큰에 아무리 많은 권한을 부여하더라도 이 동작은 토큰과 관련이 없습니다.

왜 내장된 Notion AI는 동일한 토큰으로 응답하지 않는가

Notion AI(슬래시 명령어 /AI, 워크스페이스 질문 모드, 쓰기 및 편집 어시스턴트)는 Notion 고객센터의 설명에 따라 앱 인터페이스 내에서 Shift+Cmd/Ctrl+J 단축키 또는 슬래시 명령어로 실행됩니다. 이 기능은 Business 및 Enterprise 플랜에서만 사용할 수 있으며, API나 통합 토큰(integration token)을 통해 이를 호출할 수 있는 문서화된 방법은 존재하지 않습니다.

데이터베이스 속성을 채워주는 Notion AI 생성기인 Autofill의 경우도 마찬가지입니다. 공식 Autofill 페이지에서는 수동 실행, 페이지 생성 시, 페이지 수정 시 또는 예약된 일정에 따라 실행하는 방법을 설명하고 있지만, 이는 오직 Notion 인터페이스 내에서만 가능합니다. Autofill이 기능적 맥락상 매우 "시스템적"이고 거의 자동화된 데이터베이스 기능처럼 보임에도 불구하고, 해당 페이지에는 API 트리거(API trigger)나 엔드포인트(endpoint)에 대한 언급이 전혀 없습니다.

바로 이 지점에서 개발자들은 보통 함정에 빠지게 됩니다. 검색창에 notion ai api를 입력하면 어딘가에 "생성하기", "보완하기" 또는 "답변하기"와 같은 형태의 엔드포인트가 있을 것이라는 암시를 받지만, 실제로는 레퍼런스 가이드(reference guide)를 열어도 AI 섹션이 없으며, 도움말 센터(help center)는 모든 과정을 키보드 입력과 슬래시 명령어(/command)를 통해 설명합니다. 인터페이스 내의 내장된 버튼은 외부 자동화가 가능하다는 약속처럼 보이지만, 실제로는 약속이 아닙니다. 즉, 인터페이스가 API 계약(contract)을 형성하지는 않습니다.

여기서 증거의 한계를 명확히 해둘 필요가 있습니다. Notion은 부정적인 목록(negative list)을 공개하지 않습니다. 즉, "이 기능은 API에 절대 포함되지 않을 것이다"라는 공식적이고 날짜가 명시된 성명은 없습니다. 여기서 가용한 가장 강력한 증거는 문서화의 부재입니다. 레퍼런스 가이드에도, 기능(capabilities) 엔드포인트에도 설명되어 있지 않습니다. 엔지니어링 관점에서는 이것만으로도 충분합니다. 왜냐하면 문서화되지 않은 동작(undocumented behavior)을 기반으로 구축하는 것은 어떤 경우에도 불가능하기 때문입니다. 다만, 이 결론은 영구적인 법칙이 아니라 "2026-07-18 기준으로 문서화되지 않음"으로 기록되어야 합니다.

지도: 원하는 동작, 사용 가능한 API, 대안

추상적인 경계는 구체적인 워크플로우(workflow) 항목을 통해 확인하는 것이 더 수월합니다. 아래 표는 코드를 작성하기 전 각 동작에 대해 작성해 두어야 할 실무 체크리스트입니다. 모든 상태 값은 2026-07-18 기준으로 작성되었습니다.

마지막 열은 위로를 위한 것이 아니라 해결책으로 읽어야 합니다. '별도 루프'라고 적힌 부분은 개발자가 인터페이스를 흉내 내거나 닫힌 문을 두드리는 대신, 모델 단계(model step)를 Notion 외부로 정직하게 분리해 내는 것을 의미합니다. 예를 들어, 토큰을 통해 새로운 AI 회의록을 실행하는 것과 같이 '합법적인 방법이 없다'고 적힌 부분은 정지 신호입니다. 즉, 인터페이스 우회 방법을 찾을 것이 아니라 작업을 재설계해야 한다는 뜻입니다.

Headless 브라우저를 사용하여 사용자를 대신해 /AI를 '클릭'함으로써 경계를 우회하고 싶은 유혹이 존재하지만, 이는 두 가지 검증을 동시에 통과하지 못합니다. 첫째, 필요한 동작이 문서화된 API에 존재하지 않으며, 둘째, 이 경우의 아키텍처는 에디터의 리디자인(redesign) 시 언제든 깨질 수 있는 비공식적인 UI 단계에 의존하게 됩니다. 이중 루프(Two-loop) 방식은 구축하기 더 복잡하지만, 문서화되지 않은 인터페이스 동작에 의존하지 않으므로 그 비용을 지불할 가치가 있습니다.

Notion이 2026년에 추가한 것과 경계가 사라지지 않은 이유

2026년 2월 26일자 Notion API 변경 로그 (changelog) 기록에 따르면, AI 회의록 및 transcription 블록 유형의 읽기를 지원하는 Markdown/content API가 추가되었습니다. 여기서 핵심 키워드는 '읽기'입니다. 통합(integration)을 통해 이미 존재하는 회의록의 AI 콘텐츠를 읽을 수는 있게 되었지만, 이를 생성할 수는 없습니다.

2026년 5월 11일, 별도의 엔드포인트인 Query meeting notes가 등장했습니다. 이 엔드포인트는 회의록 목록을 블록 객체(block objects) 형태로 반환하며, 통합(integration)에 연결된 사용자가 참여자로 지정됩니다. 이는 오직 콘텐츠 읽기(Read content) 권한(capability)만을 요구하며, 새로운 AI 메모를 생성(initiation)하기 위한 파라미터는 포함되어 있지 않습니다. 이는 "AI의 결과물에 대한 API 접근 권한이 AI 동작 자체에 대한 접근 권한과 동일하지 않다"는 원칙을 직접적으로 확인시켜 줍니다.

2026년 6월 22일 변경 사항(changelog)에서는 MCP(Model Context Protocol)로 연결된 외부 AI 어시스턴트(예: Claude 또는 ChatGPT)의 단일 Notion 데이터베이스 쿼리에 대한 접근 권한이 Enterprise+Notion AI 플랜에서 Business+Notion AI 플랜으로 확대되었습니다. 이는 Notion API를 호출하는 REST 통합 토큰(REST integration token)을 통한 방식이 아니라, 어시스턴트의 MCP/OAuth 통합을 통한 별도의 경로이며, Notion의 내장 AI 기능을 반복하는 것도 아닙니다. 클래식 토큰을 사용하는 개발자에게 중요한 주의 사항은 다음과 같습니다. MCP의 접근 규칙이 해당 유형의 통합으로 자동 전이되지 않으며, 이는 아키텍처적으로 다른 채널이라는 점입니다.

2026-07-18 작성된 결론: Notion은 지난 1년 동안 AI 아티팩트(artifacts)의 읽기 권한과 어시스턴트의 범위를 여러 차례 확장했지만, REST 통합을 위한 기본적인 생성 동작(Autofill, /AI, AI 블록, Q&A)은 여전히 문서화되지 않은 상태로 남아 있습니다. 기능 세트가 이미 2월, 3월, 5월, 6월에 걸쳐 변경되었으므로, 특정 "API를 통해 불가능함"에 대한 내용은 게시 날짜의 변경 사항(changelog)을 통해 반드시 재확인해야 합니다. 경계선은 세부 사항에 따라 유동적이지만, 그 논리(결과물은 읽을 수 있으나 동작은 실행할 수 없음)는 현재까지 유지되고 있습니다.

실행 가능한 이중 회로(two-circuit) 아키텍처의 모습

Notion 자체적으로 별도의 AI 계층을 위한 승인된 경로를 가지고 있습니다. 2026년 5월 13일 개발자 플랫폼 릴리스는 사용자 코드를 호스팅하는 런타임인 Workers와 외부 에이전트(Claude나 Codex 같은)를 연결하기 위한 External Agents API의 알파 버전을 설명합니다. Notion은 이를 내장된 AI 실행과 명확히 분리하며, 대체재로 제시하지 않습니다. 심지어 공급업체조차도 /AI 버튼과 그 옆에 위치한 에이전트 계층 사이에 동일한 경계를 긋고 있습니다.

첫 번째 회로의 메커니즘은 간단합니다. Autofill과 유사한 시나리오가 단 하나의 비문서화된 작업 없이 세 단계로 나뉩니다: Read content 기능 토큰이 필요한 페이지 속성을 읽어오고, 코드가 이를 외부 모델로 전송하며, 응답을 Update content를 통해 다시 작성합니다. '진짜' Autofill과의 차이점은 트리거와 모델을 개발자가 직접 선택한다는 점이며, 이것이 이 스키마가 인터페이스 외부에서 작동하는 이유입니다.

두 번째 회로는 외부 모델의 선택 및 호출에 관한 것이며, 여기서는 각 공급업체별로 별도의 SDK를 유지하는 것보다 하나의 호환 가능한 엔드포인트를 갖는 것이 편리합니다. provod.ai는 플랫폼에서 사용 가능한 모델 카탈로그(Claude, GPT, Gemini, DeepSeek, Qwen 등 현재 카탈로그 내)에 대한 단일 API 접근을 제공하며, 이는 OpenAI 및 Anthropic 프로토콜과 호환됩니다. 즉, 이미 이들 프로토콜 중 하나로 통신하는 방법을 아는 클라이언트가 통합 코드를 다시 작성할 필요 없이 base_url과 API 키를 교체하여 연결할 수 있습니다. provod.ai에 연결는 Notion AI를 대체하지 않으며 자신을 그렇게 주장하지도 않습니다. 단지 Notion REST 토큰이 호출할 수 없는 그 별도의 모델 단계만을 처리해 줄 뿐입니다.

from openai import OpenAI

client = OpenAI(
...

이 방식이 해결하지 못하는 것

이 이중 루프(Two-loop) 방식은 모든 기대를 한 번에 충족하는 것이 아니라 특정 격차를 메우는 것이며, 그 한계를 명확히 밝힐 필요가 있습니다. 이 방식은 내장된 Notion AI를 실행하지 않습니다. 즉, 개발자가 /AI, Q&A 또는 Autofill 기능을 재현하는 것이 아니라, 자신의 모델을 사용하여 유사한 결과를 재현하는 것입니다. 따라서 새로운 AI 회의록 생성과 같이 Notion 내장 AI에 특화된 기능들은 토큰을 통해서는 여전히 접근할 수 없습니다. 만약 작업이 반드시 네이티브(Native) 동작을 필요로 한다면, 이를 에뮬레이션(Emulation)할 것이 아니라 재설계해야 합니다.

또한, 이 방식은 MCP 접근을 REST 접근으로 변환하지 않습니다. MCP/OAuth를 통한 어시스턴트 범위의 확장은 그 자체의 규칙에 따라 작동하며, 이를 클래식 통합 토큰(Integration token)으로 옮길 수는 없습니다.