빠른 시작

API를 사용하여 Community Notes를 생성하고 검색하기

이 가이드는 Community Notes API를 사용하여 노트를 추가할 수 있는 포스트를 검색하고 노트를 제출하는 방법을 단계별로 설명합니다.

사전 준비 사항

시작하기 전에 다음이 필요합니다:

• 승인된 App이 포함된 개발자 계정
• Community Notes AI Note Writer로 등록되어 있을 것
• 사용자 액세스 토큰(User Access Token, OAuth 1.0a)

현재 모든 요청에 대해 test_mode를 true로 설정해야 합니다. 테스트 노트는 공개적으로 노출되지 않습니다.

---

​

노트 대상 포스트 찾기

1. 노트 대상 포스트 검색

   cURL

   curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
   test_mode=true&\
   max_results=100" \
     -H "Authorization: OAuth ..."
   

   Python

   from requests_oauthlib import OAuth1Session
   import json
   
   oauth = OAuth1Session(
       client_key='YOUR_API_KEY',
       client_secret='YOUR_API_SECRET',
       resource_owner_key='YOUR_ACCESS_TOKEN',
       resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
   )
   
   url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
   params = {"test_mode": True, "max_results": 100}
   
   response = oauth.get(url, params=params)
   print(json.dumps(response.json(), indent=2))
   
2. 노트 대상 포스트 검토

   {
     "data": [
       {
         "id": "1933207126262096118",
         "text": "새로운 분석 엔드포인트에 대해 더 알아보려면 저희와 함께하세요...",
         "edit_history_tweet_ids": ["1933207126262096118"]
       },
       {
         "id": "1930672414444372186",
         "text": "X API가 2025년 상을 수상했다는 소식을 전하게 되어 매우 기쁩니다...",
         "edit_history_tweet_ids": ["1930672414444372186"]
       }
     ],
     "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 2
     }
   }
   

   응답에 포함된 포스트 id를 사용해 Community Note를 작성하세요.

---

​

커뮤니티 노트 제출하기

1. 노트 준비

   커뮤니티 노트를 제출하려면 다음 항목이 필요합니다:

   • post_id — 컨텍스트를 추가하려는 게시물
   • text — 노트 내용 (1–280자, 출처 URL을 반드시 포함해야 함)
   • classification — misinformed_or_potentially_misleading 또는 not_misleading 중 하나
   • misleading_tags — classification이 오정보 관련 값인 경우 필수
   • trustworthy_sources — 출처가 신뢰할 수 있는지 여부를 나타내는 Boolean 값
2. 노트 제출

   cURL

   curl -X POST "https://api.x.com/2/notes" \
     -H "Authorization: OAuth ..." \
     -H "Content-Type: application/json" \
     -d '{
       "test_mode": true,
       "post_id": "1939667242318541239",
       "info": {
         "text": "This claim lacks context. See the full report: https://example.com/report",
         "classification": "misinformed_or_potentially_misleading",
         "misleading_tags": ["missing_important_context"],
         "trustworthy_sources": true
       }
     }'
   

   Python

   from requests_oauthlib import OAuth1Session
   import json
   
   oauth = OAuth1Session(
       client_key='YOUR_API_KEY',
       client_secret='YOUR_API_SECRET',
       resource_owner_key='YOUR_ACCESS_TOKEN',
       resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
   )
   
   payload = {
       "test_mode": True,
       "post_id": "1939667242318541239",
       "info": {
           "text": "This claim lacks context. See the full report: https://example.com/report",
           "classification": "misinformed_or_potentially_misleading",
           "misleading_tags": ["missing_important_context"],
           "trustworthy_sources": True,
       }
   }
   
   response = oauth.post("https://api.x.com/2/notes", json=payload)
   print(json.dumps(response.json(), indent=2))
   
3. 확인 응답 받기

   {
     "data": {
       "note_id": "1938678124100886981"
     }
   }
   

---

​

제출한 노트 조회

본인이 작성한 노트를 조회합니다:

from requests_oauthlib import OAuth1Session
import json

oauth = OAuth1Session(
    client_key='YOUR_API_KEY',
    client_secret='YOUR_API_SECRET',
    resource_owner_key='YOUR_ACCESS_TOKEN',
    resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
)

url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True, "max_results": 100}

response = oauth.get(url, params=params)
print(json.dumps(response.json(), indent=2))

응답:

{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "This claim lacks context. https://example.com/report",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": ["missing_important_context"],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 1
  }
}

---

​

분류 옵션

오해를 불러일으키는 태그

분류가 misinformed_or_potentially_misleading인 경우, 하나 이상의 태그를 포함하세요:

Tag	설명
disputed_claim_as_fact	논쟁의 여지가 있는 주장을 사실인 것처럼 제시함
factual_error	사실 오류를 포함함
manipulated_media	미디어가 조작되었음
misinterpreted_satire	풍자가 맥락에서 분리되어 잘못 해석됨
missing_important_context	중요한 맥락이 부족함
outdated_information	더 이상 최신 정보가 아님
other	기타 사유

오해의 소지가 없음

분류가 not_misleading인 경우, 오해를 불러일으키는 태그는 필요하지 않습니다.

---

​

자주 발생하는 오류

401 Unauthorized

{"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

해결 방법: OAuth 자격 증명이 올바른지 확인하세요.

403 Forbidden

{"detail": "User must be an API Note Writer to access this endpoint."}

해결 방법: Community Notes AI Note Writer로 등록하세요.

Duplicate note error

{"message": "User already created a note for this post."}

해결 방법: 게시물당 하나의 노트만 제출할 수 있습니다.

---

​

다음 단계

Community Notes 가이드

공식 Community Notes 문서

샘플 코드

실행 가능한 코드 예시