公式Xは「ベータ提供開始」と告知し、公式リポジトリは「一般には提供されていない」と記しています。Notion as Codeをめぐる説明のずれは、そこで終わりません。ワークスペースを新しく作るのか、それとも既存のものを使うのか。同じリポジトリのなかで、答えが2つ並んだままになっています。
Notionは、ワークスペースをコードで一括構築・更新できる「Notion as Code」を発表した。公式Xは2026年7月24日にベータ提供開始を告知し、ガイドとテンプレートは実験的アルファとして案内する。
構成はTypeScriptで記述し、実験用APIエンドポイント/v1/infra_as_codeへ送信する。処理は非同期で、応答のidをタスクIDとしてGET /v1/async_tasks/{taskId}に問い合わせる。ガイドは認証にボットトークンではなくパーソナルアクセストークンを求める。スクリプトはIDではなくリソースIDで対象を指定し、初回デプロイ後に返る対応表で再デプロイできる。
ガイドは新しいスペースの作成に非対応と記し、レート制限は1分あたり5リクエストとする。
From: 
How to use Notion as Code
【参考動画】
Notion CLIのデモ動画（Notion公式）
公式リリースノート「3.5: Notion Developer Platform」から案内されている実演動画。開発者およびコーディングエージェント向けCLIの操作を確認できる。
データソース連携のデモ動画（Notion公式）
同じくリリースノートから案内されている実演動画。Workersを用いた外部データの取り込みを扱う。
【編集部解説】
Notion as Codeがもたらす変化は、機能が増えることではありません。ワークスペースへの向き合い方が、根本から入れ替わることです。
これまでの公開APIは「命令型」でした。ページを1枚つくる、プロパティを1つ書き換える——そのたびにリクエストを投げ、順序もエラー処理も呼び出す側が背負う。Notion as Codeは「最終的にこうあってほしい」という構造を宣言し、対応するリソースの作成・更新をNotion側に任せます。インフラ管理でいうTerraformやPulumiと同じ発想が、ナレッジワークの器に持ち込まれたわけです。
その性格の違いは、レート制限にはっきり表れています。従来の公開APIは接続あたり平均で毎秒3リクエスト、1分に直せば約180回に相当します。対してNotion as Codeは1分あたり5リクエストです。数字だけ見れば大幅に厳しいのですが、これは1リクエストが1エンティティに対応しなくなったことの裏返しでもあると考えられます。1回の送信で、チームスペースもページも一気に立ち上がる。粒度そのものが変わっています。
構成の正本はTypeScript、失うと困るのは対応表のJSONです
実務でいちばん注意したいのは、リソースIDとNotionレコードの対応表です。
どういう構成にしたいかを書くのはTypeScriptのソースであり、そちらがgitで管理される設計図です。一方、初回の適用後に返ってくる対応表は、その設計図とNotion上の実物とを結びつける台帳にあたります。役割が違うため、片方をバージョン管理していても、もう片方を失えば話が変わります。
対応表は {"hub-page": {"id": "456", "table": "block"}} のような形で返ってきます（ガイドが示す簡略な例です）。次に再デプロイするとき、これを existingResources として渡せば同じレコードが更新される。渡さなければ、新しいレコードが作られます。
Terraformでいうstateファイルのうち、リソースの識別を担う部分に近い役割です。少なくとも公開されている仕様上、この対応表を渡さなければ、Notionは新しいレコードを作ります。
つまり、この対応表を失えば、更新のつもりが複製になる。gitで構成を管理するなら、この台帳の保管とバックアップも同じ強度で設計しておく必要があります。
「gitで追える」という言葉に、Notion特有の落とし穴があります
発表直後、Xでは、TypeScriptで宣言する部分は簡単なほうで、誰かが手でデータベースを編集した瞬間にgitは体裁のいい記録になってしまう、という指摘も出ています。
これは的を射た論点だと私は考えています。IaCの世界では「ドリフト」と呼ばれる古典的な問題ですが、Notionではより厄介になる可能性があります。IaCで管理するクラウドインフラでは、手動での変更を避け、操作をコードと変更管理の経路に集約する運用が定石です。しかしNotionは、エンジニアでない人が自由に構造を組み替えられることを価値の中心に据えてきた道具です。
コードで宣言された構造と、現場が育てていく構造。この2つをどう共存させるかは、機能では解けません。運用ルールの設計が問われます。
認証がボットから「個人」に変わる意味
もう1点、見落としやすい仕様があります。ガイドが説明する手順では、従来のボットトークンではなくパーソナルアクセストークンを要求します。現在の公式テンプレートではCLIによるログインも使えます。いずれの場合も、処理は個人がワークスペースへのアクセスを認可して得た資格情報で実行されます。
パーソナルアクセストークンは、2026年5月13日のNotion Developer Platform（3.5）で整備されたものです。裏を返せば、デプロイはその個人の権限で実行されます。コーディングエージェントにスクリプトを渡して走らせるとき、動いているのは「誰か」の権限です。組織で運用するなら、監査ログなど利用可能な記録と合わせて、誰の権限で何が展開されたかを追える体制が前提になります。
ワークスペースの扱いは、まだ定まっていません
元のガイドには「既存スペース内での作成・更新のみで、新しいスペースはまだ作れない」とあります。ところが現行テンプレートの型定義は、その逆を書いています。スクリプトは新しいスペースを作ることが必須で、既存スペース内では動作できない、と。
しかも理由が明記されています。すべての操作を、実行ユーザーが完全な所有権を持つ新規スペース内で行わせるため。権限の安全性のための制約だというわけです。
一方で、同じリポジトリの公式サンプルはログイン中のワークスペースを起点にしており、型定義が「サポートしない」と書いた操作をそのまま実行しています。公式資料のなかで、説明が食い違ったままです。
ここは仕様の揺れとして受け止めるのが正確でしょう。ただ、型定義に書かれた理由のほうは示唆的です。先ほど触れた「個人の権限で動く」という問題を、Notion自身も課題として認識している。その答えのひとつが、まっさらなスペースを強制することだった。そう読めます。
現時点の立ち位置を、正確に把握しておきたい
呼称にはばらつきがあります。公式Xアカウントは2026年7月24日（日本時間）に「ベータ」として告知しました。一方、ガイド本体は承認制のアルファとして案内し、本番ワークスペースではなく新しいワークスペースで試すよう勧めています。正式ローンチまで破壊的変更が入る可能性も明記されています。
同じ7月24日にNotionが公式リリースノートに掲載したのは、Workersのクレジットダッシュボード対応でした。Notion as Codeは、この時点でリリースノートには載っていません。実験的な位置づけであることが、公開の仕方そのものに表れていると読めます。
なお、この仕組みにはNotion公式のテンプレートリポジトリが用意されています。ntn notion-as-code apply というCLIコマンドで適用する流れに移りつつあり、対応表の受け渡しもCLIが引き受ける形に整理されました。
ただし、そのテンプレートのREADMEにはこう書かれています。実験的であり、一般には提供されていない。環境によってはAPIがリクエストを拒否することがある、と。公式Xの「ベータ提供開始」という言葉と、公式リポジトリのこの但し書きのあいだには、まだ距離があります。
つまり設計思想は完成に近づいている一方、提供の実態はまだ実験段階にある。この2つを分けて受け取っておくのが、いま最も正確な理解だと考えています。
ページやデータベースについても、原則としてスクリプト外の既存レコードを親に指定できないなど、対応範囲には制約があります。今すぐ社内標準にする段階ではなく、検証用ワークスペースで感触をつかむ時期でしょう。
それでも、この一歩は大きいと思う理由
Notionは3.5で開発者向け基盤を、5月にアルファ発表した外部エージェントAPIを7月1日の3.6で開放し、ClaudeとCursorを最初の2つとして迎えました。Custom Agentsは2026年2月24日のバージョン3.3で登場し、5月上旬までに100万個以上がつくられました。Notion as Codeは、その延長線上に置かれた最後のピースに見えます。
エージェントが働く場所を用意するのに、人間が延々とクリックしている——その矛盾を解消しにきた、ということです。
そしてもう少し先を見るなら、意味はさらに広がります。組織の構造がコードになれば、「なぜこの部署にこのデータベースがあるのか」という問いに、コミット履歴が答えを返すようになる。組織設計が、レビュー可能な対象になるということです。
私たちが働く場所そのものが、ソフトウェアと同じ扱いを受け始めている。この記事を今書いておきたいと考えたのは、その入り口が見えたからです。
【関連記事】
Notion 3.5｜サーバー不要でコードが走る──「Developer Platform」の設計思想
今回の前提となるNotion Workers、CLI、External Agents APIを解説した記事。ntnコマンドの出自がわかる。
Notionの「公開する」が危ない—2022年から続く認証不要APIによる個人情報漏洩の実態
NotionのAPI設計と権限をめぐる問題を追った記事。今回の権限の安全性という論点につながる。
ジャック・ドーシーが「Buzz」を発表｜人間とAIエージェントが同じチームで働く業務チャット
人間とAIが同じ権限管理と記録の仕組みで働く基盤を紹介した記事。設計の方向性を比較できる。
【編集部後記】
まっさらなスペースを作らせる理由が、権限の安全性だと型定義に明記されていました。実行する人が完全な所有権を持つ場所でしか動かさない、という設計です。裏を返せば、既存のワークスペースに手を入れさせるのは危ういという判断でもあります。
この方針が残れば、Notion as Codeは「いま使っているワークスペースをコードで管理する道具」ではなく「新しいワークスペースを配る道具」になります。すでに育ちきった自社の構造を整理したい人の期待とは、そこでずれます。
どちらの姿で正式版が出てくるのか、引き続き注目していきたいと思います。
【用語解説】
Notion as Code
Notionのワークスペース構成をコードで記述し、API経由で一括反映するしくみ。TypeScriptで「最終的にどうあってほしいか」を書き、宣言したリソースの作成・更新はNotion側が担う。2026年7月時点では実験的なアルファとして限定的に提供されている。
宣言型と命令型
命令型は「何をどの順で実行するか」を1手ずつ指示する方式。宣言型は「最終的な状態」だけを記述し、そこへ至る手順はツールが決める方式である。従来の公開APIが前者、Notion as Codeが後者にあたる。
IaC（Infrastructure as Code）
サーバーやネットワークの構成をコードとして記述し、バージョン管理・レビュー・再現を可能にする手法。TerraformやPulumiが代表格である。Notion as Codeは、この考え方をワークスペース構成に持ち込んだものといえる。
リソースID
Notion as Codeのスクリプト内で、作成対象を識別するために利用者が付ける名前。実際のNotionのIDとは異なり、一意で安定していることが求められる。初回デプロイ後に、リソースIDと実レコードの対応表が返される。
stateファイル
IaCツールが、コード上の定義と実際の環境との対応関係を記録しておくファイル。Terraformでは差分計算の基準となる。Notion as Codeで返される対応表は、このうちリソースの識別を担う部分に近い役割を持つ。
ドリフト（drift）
コードで定義された構成と、実環境の状態がずれていく現象。手作業による直接変更が主な原因となる。IaC運用における代表的な課題である。
パーソナルアクセストークン
特定の個人アカウントに紐づく認証情報。ボット用トークンと異なり、その個人が持つメンバーシップとページ権限の範囲で操作が実行される。2026年5月のNotion Developer Platformで整備された。
非同期API・ポーリング
リクエストを送った時点では処理が完了せず、受付番号だけが返る方式が非同期API。利用者は別のエンドポイントに定期的に問い合わせ（ポーリング）、完了を待つ。
レート制限
一定時間内に送れるリクエスト数の上限。Notionの公開APIは接続あたり平均で毎秒3リクエストを基準とし、ワークスペース単位の上限も別に設けられている。いずれかを超えるとHTTP 429が返る。またNotionが一時的に過負荷のときはHTTP 529が返り、どちらもRetry-Afterに従った再試行やバックオフで対処する。Notion as Codeは1分あたり5リクエストと定められている（2026年7月時点）。
スペースとチームスペース
Notionの内部呼称では、スペースが契約単位のワークスペース、チームスペースはその内側で部署やプロジェクト単位にページとメンバーをまとめる区画にあたる。Notion as Codeでは、いずれもコードで定義する記法が用意されている。
コーディングエージェント
自然言語の指示を受けてコードを書き、実行まで担うAIツールの総称。ClaudeやCursorなどが該当する。Notionは2026年7月のバージョン3.6で、これらを外部エージェントとして受け入れる機能を開放した。
TypeScript
JavaScriptに静的な型付けを加えたプログラミング言語。型定義によって記述ミスを実行前に検出しやすい。Notion as Codeの構成記述はこの言語で行う。
【参考リンク】
Notion（日本語公式サイト）（外部）
ドキュメント、データベース、AIエージェントを統合したワークスペースを提供するNotion Labs, Inc.の公式サイトである。
Notion「What’s New」（外部）
Notionの公式リリースノート一覧。バージョン3.3、3.5、3.6を含む各更新の内容と公開日が時系列で確認できる。
Notion「3.5: Notion Developer Platform」（外部）
2026年5月13日公開。Workers、CLI、パーソナルアクセストークンなど、今回の前提となる開発者基盤の発表回である。
Notion Docs「Request limits」（外部）
公開APIのレート制限に関する公式リファレンス。接続単位とワークスペース単位の2種類の上限が明記されている資料である。
Notion Workers ドキュメント（外部）
Notionのインフラ上でカスタムコードを実行するWorkersの公式ドキュメント。導入手順と設計方針が解説されている。
makenotion/notion-as-code-template（GitHub）（外部）
Notion as Code用の公式テンプレート。READMEは実験的アルファであり一般提供されていないと明記している。
makenotion/notion-sdk-js（GitHub）（外部）
Notion公式のJavaScript SDKリポジトリ。Notion as Codeは実験用ブランチで提供されている。
Notion公式Xアカウントの発表投稿（外部）
2026年7月24日（日本時間）投稿。Notion as Codeのベータ提供開始を告知した一次情報にあたる投稿である。
Terraform（HashiCorp Developer）（外部）
IaCの代表的ツールの公式ドキュメント。宣言型構成、stateファイル、ドリフト検出といった概念の原典にあたる資料である。
Pulumi「Pulumi vs. Terraform」（外部）
TypeScriptなど汎用言語でインフラを記述するPulumiによる比較解説。両者の設計思想の違いを理解する助けになる。
【参考記事】
3.5: Notion Developer Platform（Notion）（外部）
2026年5月13日公開の公式リリースノート。Workers、CLI、外部エージェントAPIを一挙に発表した回である。
Request limits（Notion Docs）（外部）
接続あたり平均で毎秒3リクエスト、超過時はHTTP 429とrate_limitedが返ると明記する公式資料である。
3.3: Custom Agents（Notion）（外部）
2026年2月24日公開。Custom Agentsの提供開始を告げ、初期テスターが21,000個を作成したと記す。
What’s New（Notion）（外部）
7月24日の掲載はWorkers対応であり、Notion as Codeが一覧に含まれていないことを確認できる。
What is Terraform（HashiCorp Developer）（外部）
stateファイルで実環境を追跡し、既定では適用前に実行計画を提示して承認を求める設計を解説している。
Notion launches beta to deploy workspaces as TypeScript（Digg）（外部）
発表直後のX上の反応を整理した記事。手作業の編集でgitの記録が実態と乖離するという指摘も併記する。
How to Integrate with the Notion API（Truto）（外部）
毎秒3リクエストは15分あたり2700回に相当し、複雑なページの読込には103回の呼び出しが必要と試算する。
Notion 3.5｜サーバー不要でコードが走る──「Developer Platform」の設計思想
今回の前提となるNotion Workers、CLI、External Agents APIを解説した記事。あわせてお読みください。
