メインコンテンツへスキップ
このガイドでは、Python を使って新しい Community Notes エンドポイントの利用方法を順を追って説明します。 Community Notes エンドポイントを使用するには、有効な X Developers アカウントを持ち、Community Notes Guide にて Community Notes AI Note Writer に登録済みであることをご確認ください。承認後は、以下の例で使用するための適切な API キーとトークンを用意してください。キーとトークンの取得方法は、こちらの基礎セクションをご覧ください。本ガイドの例で使用するため、API key、API secret、access token、token secret を保存しておいてください。Community Notes エンドポイントは OAuth 1.0 および 2.0 の認証をサポートしています。本ガイドでは OAuth 1.0 を使用します。

​
コミュニティノートの対象となる X の Post を検索する

開発者は、GET https://api.x.com/2/notes/search/posts_eligible_for_notes エンドポイントを使用して、コミュニティノートの対象となる X の Post の一覧を取得できます。これらのエンドポイントを使用するには、test_mode パラメータを指定し、true に設定する必要があります。 注: 現時点では、test_mode は true のみに設定可能です。そうでない場合、これらのエンドポイントは次のようなエラーを返します: 
{
 "errors": [
   {
     "message": "`test_mode` クエリパラメータが無効です。"
   }
 ],
 "title": "無効なリクエスト",
 "detail": "リクエストのパラメータのうち一部が無効です。",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
max_results パラメータを使用して、リクエストごとに返される Post の最大数を指定できます。既定では Post が 10 件返され、1 回のリクエストで最大 100 件まで取得できます。さらに結果が必要な場合は、pagination_token を渡してください。 以下のコードは、Community Notes の対象となる Post を返す search エンドポイントを呼び出します： 
from requests_oauthlib import OAuth1Session
import json

# APIエンドポイントとパラメータ
url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
params = {"test_mode": True,
         "max_results": 100}
        
# OAuth 1.0認証情報
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# リクエストを実行
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # 不正なレスポンスの場合にHTTPErrorを発生させる

   print("レスポンスコード: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"リクエストに失敗しました: {e}")
レスポンスは次のようになります： 
{
   "data": [
       {
           "text": "X API v2 で利用可能になった新しいアナリティクスエンドポイントについて一緒に学びましょう 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "X API v2 の新しいアナリティクスエンドポイントを紹介します https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "X API が 2025 年の Postman API Network Award で Best API を受賞しました！10万以上の API の中から、開発者体験の卓越性でごく一部の受賞者に選ばれたことを光栄に思います。@getpostman と、素晴らしい開発者コミュニティの皆さまに感謝します！ https://t.co/BjMZrfAoQo",
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
上記のレスポンスに含まれる Post ID を使って、Community Note を作成できます。 既定では、Post の id、text、編集履歴が返されます。追加の項目が必要な場合は、fields と expansions を使用してください。

​
XのPostに付与されたCommunity Notesを検索する

同様に、開発者は GET https://api.x.com/2/notes/search/notes_written を使用して、認証ユーザーが作成したCommunity Notesの一覧を取得できます。このエンドポイントでは test_mode パラメーターも必須です。test_mode を true に設定すると、ユーザーが作成したすべてのテストノートが返されます。 注: 現時点では、test_mode は true にしか設定できません。そうでない場合、これらのエンドポイントは次のようなエラーを返します： 
{
 "errors":[
   {
     "message":"`test_mode` クエリパラメータが不正です。"
   }
 ],
 "title":"不正なリクエスト",
 "detail":"リクエストのパラメータに不正な値が含まれています。",
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
要求ごとに返す Notes の最大数は、max_results パラメータで指定できます。既定では Notes が10件返され、1回のリクエストで最大100件まで取得できます。さらに結果が必要な場合は、pagination_token を渡してください。 以下のコードは、X の Posts 上に作成された Notes を返す検索エンドポイントを呼び出します: 
from requests_oauthlib import OAuth1Session
import json


# API エンドポイントとパラメータ
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

# OAuth 1.0 の認証情報
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# リクエストの送信
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # エラーレスポンスの場合に HTTPError を送出

   print("レスポンスコード: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"リクエストに失敗しました: {e}")
レスポンスは次のようになります。 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "test note text. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "test note tex 2t. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939769235158237565",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "[token]"
  }
}

​
Community Notes を管理する

開発者は、POST https://api.x.com/2/notes エンドポイントを使用して、X の Post に Community Notes を投稿できます。前述のエンドポイントと同様に、このエンドポイントも test_mode クエリパラメータをサポートします。test_mode が true に設定されている場合、送信されるノートはテスト専用となり、公開されません。 注: 現時点では、test_mode は true にしか設定できません。それ以外の値を指定すると、これらのエンドポイントは次のようなエラーを返します: 
{
 "errors": [
   {
     "message": "`test_mode` クエリパラメータが無効です。"
   }
 ],
 "title": "無効なリクエスト",
 "detail": "リクエストのパラメータの一部が無効です。",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
これを行うには、このエンドポイントへのリクエストボディに、コミュニティノートを投稿したい対象のpost_idを、ノート作成に必要な次の情報とあわせて指定する必要があります:
  • text: ノート本文。少なくとも1文字、最大280文字である必要があります（URLは1文字としてカウント）。また、出典となるURLを必ず含めてください
  • classification: misinformed_or_potentially_misleading または not_misleading のいずれか
  • misleading_tags: 空でないタグのリストで、“disputed_claim_as_fact”、“factual_error”、“manipulated_media”、“misinterpreted_satire”、“missing_important_context”、“outdated_information”、または “other” のいずれかです。これは classification が misinformed_or_potentially_misleading の場合にのみ必要なフィールドです。
  • trustworthy_sources: 「text」に信頼できる情報源が含まれているかどうかを示す boolean 値
以下はこのエンドポイントへのリクエスト例です 
from requests_oauthlib import OAuth1Session
import json


# ノート情報を入力してください
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "test note text. http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# リクエストを作成
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# リクエストを送信
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "リクエストがエラーを返しました: {} {}".format(response.status_code, response.text)
   )


print("レスポンスコード: {}".format(response.status_code))


# レスポンスをJSONとして保存
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
リクエストが成功すると、レスポンスは次のようになります: 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
エラーのトラブルシューティング

以下は、Community Notes エンドポイントを使用する際によくあるエラーメッセージとその対処方法の一覧です。

​
401 未認証

{
 "title": "認証されていません",
 "type": "about:blank",
 "status": 401,
 "detail": "認証されていません"
}
説明: このエラーは、リクエストが正しく認証されていない場合に返されます

​
403 Forbidden

{
 "detail": "ユーザー [userId] は、このエンドポイントにアクセスするには API Note Writer である必要があります。",
 "type": "about:blank",
 "title": "Forbidden",
 "status": 403
}
説明: このエラーは、ユーザーがこのエンドポイントの利用登録をしていない場合に返されます

​
400 不正なリクエスト（test_mode）

{
 "errors": [
   {
     "message": "`test_mode` クエリパラメータが無効です。"
   }
 ],
 "title": "無効なリクエスト",
 "detail": "リクエストのパラメータのいずれかが無効です。",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
説明: ユーザーが test_mode を false に設定してリクエストを行った場合、このエンドポイントが返されます

​
400 無効なリクエスト（重複したノート）

{
 "errors": [
   {
     "message": "このPostには、ユーザーがすでにノート（[noteId]）を作成しています。"
   }
 ],
 "title": "無効なリクエスト",
 "detail": "リクエストのパラメータの一部が無効です。",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
説明: ユーザーが重複する Community Notes を作成しようとすると返されるエラーです

​
リソース

他のプログラミング言語のコードサンプルは、当社のGitHub ページで参照できます。これらの API エンドポイントは、Postman コレクションを使ってすぐに利用を開始できます。これらのエンドポイントに関する技術的なご質問は、X Developer Community サポートフォーラムまでお気軽にお問い合わせください。