<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 に関する規則

コードサンプルと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 エンドポイント固有の結果のリスト（またはその一部）。詳細については、サポートされているエンドポイントの個別のドキュメントを参照してください。

リクエスト制限

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

レート制限

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

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

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

</aside>

サイズ制限

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

プロパティ値の種別 内部プロパティ サイズ制限
リッチテキストオブジェクト text.content 2,000文字
リッチテキストオブジェクト text.link.url 2,000文字
リッチテキストオブジェクト equation.expression 1,000文字
一連のリッチテキストオブジェクト 100要素

ステータスコード

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

サクセスコード

HTTPステータスコード 概要
200 リクエストの処理に成功

エラーコード

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

HTTPステータスコード code message
400 invalid_json リクエスト・ボディをJSONとしてデコードできませんでした。
invalid_request_url このリクエストURLは無効です。
invalid_request このリクエストはサポートされていません。
401 unauthorized ベアラートークンが無効です。

バージョン設定

私たちの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が返すほぼすべてのオブジェクトで表示されます。以下に主な例を示します。

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

すべてのユーザー

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

プロパティ 更新可否 型 概要 値の例
object* 表示のみ可 "user" 常に "user" "user"
id* 表示のみ可 string(UUID) そのユーザーの一意の識別子 "e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
type 表示のみ可 string(任意/列挙型) ユーザーの種別で、"person" または "bot" "person"
name 表示のみ可 string(任意) Notion上で表示されるユーザー名 "山田 太郎"
avatar_url 表示のみ可 string(任意) 選択されたプロフィール画像 "<https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg>"

ファイル

ファイルオブジェクトには、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ブックマークのブロックタイプは、すべてファイルオブジェクトを含みます。アイコンおよびカバー画像のページオブジェクト値も、ファイルオブジェクトを含んでいます。

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

フィールド 型 概要 値の例
type string (列挙型) ファイルオブジェクトの種類。
"external" または "file"。 "external"
external file object タイプ固有の設定を含むオブジェクト。オブジェクトのキーは、外部ファイルの場合は external 、Notionホストファイルの場合は file となる。タイプ固有の値の詳細については、型のセクションを参照。

エンドポイント

エンドポイント