概要

本リファレンスは、Notion API を包括的に理解するために役立ちます。

インテグレーションは API を使用して、Notion のページ、データベース、およびユーザーにアクセスします。インテグレーションにより、サービスを Notion に接続し、Notion 内のユーザー向けのインタラクティブなエクスペリエンスを構築できます。左側のナビゲーションを使用すると、API で使用されるオブジェクトとエンドポイントの詳細が表示されます。

📘
Notion API とやり取りするには、インテグレーショントークンが必要です。インテグレーション設定ページでインテグレーションを作成した後、インテグレーショントークンを見つけることができます。初めて Notion API を使用する場合は、入門ガイドから始めて、インテグレーションの作成方法を学習することをお勧めします。
特定のインテグレーションに取り組みたいが、トークンにアクセスできない場合は、関連するワークスペースの管理者であることを確認してください。Notion UI の左側のサイドバーの Settings & Membersから確認できます。どのワークスペースの管理者でもない場合は、個人用ワークスペースを無料で作成できます。

規約

すべての API リクエストを送信するベース URL はhttps://api.notion.comです。すべての API リクエストに HTTPS が必要です。

Notion API は可能な限り RESTful 規則に従い、ほとんどの操作はページおよびデータベースリソースでGET、POST、PATCH、DELETEリクエストを介して実行されます。リクエストとレスポンスの本文は、JSON としてエンコードされます。

JSON 規則

トップレベルのリソースにはobjectプロパティがあります。このプロパティは、リソースのタイプ ( database、user など) を決定するために使用できます。

トップレベルのリソースは、UUIDv4"id"プロパティによってアドレス指定できます。ID を Notion URL からコピーする場合など、API にリクエストを行うときは、ID からダッシュを省略できます。

プロパティ名はsnake_case(camelCaseまたはkebab-caseではない) にあります。

時間値 (日付と日時) は、ISO 8601文字列でエンコードされます。日時には時刻値 (2020-08-12T02:12:33.231Z ) が含まれますが、日付には日付のみが含まれます。 (2020-08-12 )

Notion API は空の文字列をサポートしていません。たとえば、urlProperty value objectなどのプロパティの文字列値を設定解除するには、""の代わりに明示的なnull を使用します。

コードサンプルと SDK

エンドポイントごとにサンプルのリクエストとレスポンスが示されています。リクエストは、Notion JavaScript SDKおよびcURLを使用して表示されます。これらのサンプルを使用すると、インテグレーションを構築するときに簡単にコピー、貼り付け、および変更できます。

Notion SDK は、インストールして簡単にビルドを開始できるオープンソースプロジェクトです。HTTP リクエストを作成できる他の言語またはライブラリを選択することもできます。

ページネーション

オブジェクトのリストを返すエンドポイントは、カーソルベースのページネーションリクエストをサポートしています。デフォルトでは、Notion は API 呼び出しごとに 10 個のアイテムを返します。サポートエンドポイントからの応答のアイテム数がデフォルトを超える場合、インテグレーションはページネーションを使用して特定の結果セットを要求したり、返されるアイテムの数を制限したりできます。

サポートされているエンドポイント

HTTP メソッド	終点
GET	すべてのユーザーを一覧表示する
GET	ブロックの子を取得する
GET	コメントを取得する
GET	ページプロパティアイテムを取得する
POST	データベースにクエリを実行する
POST	検索

レスポンス

エンドポイントがページネーションをサポートしている場合、レスポンスオブジェクトには以下のフィールドが含まれます。

分野	タイプ	説明
`has_more`	`boolean`	レスポンスにリストの最後が含まれるかどうか。それ以上の結果がない場合`false`なり、そうでなければ`true`になります。
`next_cursor`	`string`	値を`start_cursor`パラメータとして同じエンドポイントに渡すことで、結果の次のページを取得するために使用できる文字列。`has_more`が true の場合にのみ使用できます。
`object`	`"list"`	定数文字列`"list"`。
`results`	`array of objects`	エンドポイント固有の結果のリストまたは部分的なリスト。詳細については、サポートされているエンドポイントの個別のドキュメントを参照してください。
`type`	`"block"` `"comment"` `"database"` `"page"` `"page_or_database"` `"property_item"` `"user"`	`results`内のオブジェクトのタイプを表す定数文字列。
`{type}`	`paginated list object`	タイプ固有のページネーション情報を含むオブジェクト。`property_item`の場合、値は分割されたページプロパティタイプに対応します。他のすべてのタイプの場合、値は空のオブジェクトです。

ページ分割されたリクエストのパラメータ

🚧パラメーターの場所はエンドポイントによって異なります
GETリクエストは、クエリの文字列のパラメーターを受け入れます。
POSTリクエストは、リクエストのBodyでパラメーターを受け取ります。

パラメータ	タイプ	説明
`page_size`	`number`	レスポンスに含める完全なリストからのアイテムの数。デフォルト:`100`最大: `100` レスポンスに含まれる結果の数がデフォルトよりも少ない場合があります。
`start_cursor`	`string`	以前のレスポンスで返された`next_cursor`値。これを不透明な値として扱います。デフォルトは`undefined` で、リストの先頭から結果を返します。

ページ分割されたリクエストを送信する方法

サポートされているエンドポイントに最初のリクエストを送信します。

レスポンスからnext_cursor値を取得します(has_more がtrue の場合のみ利用可能)。

クエリ文字列 (GETリクエストの場合) またはBodyパラメーター (POSTリクエスト)にnext_cursorパラメーターを含むフォローアップリクエストをエンドポイントに送信します。

例: データベースから次の一連のクエリ結果をリクエストする

curl --location --request POST 'https://api.notion.com/v1/databases/<database_id>/query' \
--header 'Authorization: Bearer <secret_bot>' \
--header 'Content-Type: application/json' \
--data '{
    "start_cursor": "33e19cb9-751f-4993-b74d-234d67d0d534"
}'

概要

概要#

📘#

規約#

JSON 規則#

コード サンプルと SDK#

ページネーション#

サポートされているエンドポイント#

レスポンス#

ページ分割されたリクエストのパラメータ#

🚧パラメーターの場所はエンドポイントによって異なります#

ページ分割されたリクエストを送信する方法#

例: データベースから次の一連のクエリ結果をリクエストする#

概要

📘

規約