<aside> ❗ Notionヒント： このページは作成例です。APIリファレンスをNotionでホストする際の構成例としてご参照ください。 エンドポイントデータベースには、さらに詳細なエンドポイントテンプレートも含まれています。

</aside>

一般

はじめに

このリファレンスは、Notion APIを包括的に理解するための情報を記載しています。

<aside> ❗ Notion APIとやり取りするには、インテグレーショントークンが必要です。インテグレーショントークンは、インテグレーションを作成した後のインテグレーション設定ページで確認できます。初めてNotion APIをお使いになる場合は、入門ガイド（英語）でインテグレーションの作成方法を学ぶことをお勧めします。

</aside>

規則

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

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

JSON に関する規則

• トップレベルのリソースは "object" プロパティを持ちます。このプロパティはリソースのタイプ ("database" や "user" など) を判別するために使用されます。
• トップレベルのリソースは UUIDv4 の "id" プロパティでアドレス指定することができます。APIにリクエストする場合、例えばNotion URLからIDをコピーする場合、IDからはダッシュを省略することが可能です。
• プロパティ名は snake_case で記述します。（camelCase や kebab-case は不可）
• 時間的な値（dateとdatetime）はISO 8601の文字列でエンコードされます。datetimeは時刻の値 (2020-08-12T02:12:33.231Z) まで含みますが、dateは日付 (2020-08-12)のみとなります。
• Notion API は空の文字列をサポートしていません。例えば、urlプロパティ値オブジェクト のようなプロパティの文字列値の設定を解除するには、""の代わりに明示的に null を使用します。

コードサンプルとSDK

各エンドポイントについて、リクエストとレスポンスのサンプルを示します。リクエストは、Notion JavaScript SDK と cURL を使用しています。これらのサンプルを使用すると、インテグレーションを構築する際にコピー・ペースト・修正を簡単に行うことができます。

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

ページネーション

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

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

レスポンス

リクエスト制限

すべての API ユーザーに一貫した開発者体験を保証するため、Notion API にはレート制限があり、リクエストパラメータには基本的なサイズ制限が適用されます。

レート制限

レート制限されたリクエストは "rate_limited" エラーコード (HTTP レスポンスステータス 429) を返します。**インテグレーションごとの受信リクエストのレート制限は、平均で毎秒3リクエストです。**平均レートを超えるバーストも許可されることがあります。

<aside> ❗ レート制限は変更になる可能性があります

将来的には、需要と信頼性のバランスを考慮し、レートの上限を調整する予定です。また、異なる料金プランのワークスペースに個別のレート制限を導入する可能性もあります。

</aside>

サイズ制限

Notion は特定のパラメータのサイズとリクエストの子要素の深さを制限しています。これらの制限を超えたリクエストは "validation_error" エラーコード（HTTP レスポンスステータス 400）を返し、"message" プロパティに詳細が記述されます。

ステータスコード

HTTPレスポンスコードは、成功とエラーの一般的なクラスを示すために使われます。

サクセスコード

エラーコード

エラーレスポンスには、レスポンスボディの "code" プロパティと "message" プロパティに、エラーの詳細が含まれています。

バージョン設定

私たちのAPIバージョンには、そのバージョンがリリースされた日付の名前が付けられています。（例：2022-06-28）

バージョン設定は Notion-Version ヘッダを含めることで行います。Notion-Version ヘッダーの設定は 必須 です。

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

オブジェクト

ユーザー

ユーザーオブジェクトがAPIに表示される場所

ユーザーオブジェクトは、APIが返すほぼすべてのオブジェクトで表示されます。以下に主な例を示します。

• ブロックオブジェクト： created_by および last_edited_by の下
• ページオブジェクト： created_by および last_edited_by の下、people プロパティアイテム内
• データベースオブジェクト： created_by および last_edited_by の下
• リッチテキストオブジェクト： ユーザーメンションとして
• プロパティオブジェクト： プロパティが people 形式の場合

ユーザーオブジェクトは後述するように、object キーと id キーを常に含んでいます。残りのプロパティは、ユーザがリッチテキストまたはページプロパティのコンテキストでレンダリングされ、ボットがそれらのプロパティにアクセスするための適切なケイパビリティを持っている場合に表示されることがあります。ケイパビリティの詳細については、ケイパビリティガイドと認証ガイドを参照してください。（いずれも英語）

すべてのユーザー

これらのフィールドは、人やボットを含むすべてのユーザーによって共有されます。アスタリスクの付いたフィールドは常に存在します。

ファイル

ファイルオブジェクトには、Notion にアップロードされたファイルに関するデータ、または Notionでリンクされた外部ファイルに関するデータが含まれます。

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

ページ、埋め込み、画像、動画、ファイル、PDF、Webブックマークのブロックタイプは、すべてファイルオブジェクトを含みます。アイコンおよびカバー画像のページオブジェクト値も、ファイルオブジェクトを含んでいます。

各ファイルオブジェクトは以下のフィールドを含みます。

エンドポイント

エンドポイント