메인 콘텐츠로 건너뛰기
이 가이드에서는 Python으로 새로운 Community Notes 엔드포인트 사용 방법을 안내합니다. Community Notes 엔드포인트를 사용하려면 유효한 X Developers Account가 있어야 하며, 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 게시물 검색

개발자는 GET https://api.x.com/2/notes/search/posts_eligible_for_notes 엔드포인트를 사용하여 커뮤니티 노트를 받을 수 있는 X 게시물 목록을 조회할 수 있습니다. 이 엔드포인트를 사용하려면 test_mode 매개변수를 지정하고 true로 설정해야 합니다. 참고: 현재는 test_mode를 true로만 설정할 수 있으며, 그렇지 않으면 다음과 같은 오류가 반환됩니다: 
{
 "errors": [
   {
     "message": "`test_mode` 쿼리 매개변수가 올바르지 않습니다."
   }
 ],
 "title": "잘못된 요청",
 "detail": "요청에 포함된 하나 이상의 매개변수가 올바르지 않습니다.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
요청마다 반환할 게시물의 최대 개수는 max_results 매개변수로 지정할 수 있습니다. 기본적으로 게시물 10개가 반환되며, 요청당 최대 100개까지 가져올 수 있습니다. 더 많은 결과가 필요하면 pagination_token을 전달하세요. 아래 코드는 Community Notes 대상 게시물을 반환하는 검색 엔드포인트를 호출합니다: 
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 최우수 API 부문을 수상했다는 소식을 전하게 되어 매우 기쁩니다! 100,000개 이상의 API 중 극소수만이 선정되는 수상자 그룹에 포함되어 뛰어난 개발자 경험을 인정받았습니다. @getpostman과 우리의 훌륭한 개발자 커뮤니티에 감사드립니다! https://t.co/BjMZrfAoQo",
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
위의 응답에서 받은 게시물 ID를 사용해 커뮤니티 노트를 작성할 수 있습니다. 기본적으로 게시물 id, 텍스트, 편집 기록이 제공됩니다. 추가 필드가 필요하면 fields와 expansions를 사용할 수 있습니다

​
X 게시물에 작성된 Community Notes 검색

마찬가지로 개발자는 인증된 사용자가 작성한 Community Notes 목록을 GET https://api.x.com/2/notes/search/notes_written을 사용하여 가져올 수 있습니다. 이 엔드포인트에는 test_mode 매개변수도 필요합니다. test_mode가 true로 설정되면 사용자가 작성한 모든 테스트 노트가 반환됩니다. 참고: 현재는 test_mode를 true로만 설정할 수 있으며, 그렇지 않으면 해당 엔드포인트들은 다음과 같은 오류를 반환합니다: 
{
 "errors":[
   {
     "message":"`test_mode` 쿼리 매개변수가 유효하지 않습니다."
   }
 ],
 "title":"잘못된 요청",
 "detail":"요청에 포함된 하나 이상의 매개변수가 유효하지 않습니다.",
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
요청당 반환할 노트 최대 개수는 max_results 매개변수로 지정할 수 있습니다. 기본값은 10개이며, 요청당 최대 100개의 노트를 가져올 수 있습니다. 추가 결과가 필요하면 pagination_token을 전달하세요. 아래 코드는 X 게시물에 작성된 노트를 반환하는 검색 엔드포인트를 호출합니다: 
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": "테스트 노트 텍스트. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "테스트 노트 텍스트 2. 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]"
  }
}

​
커뮤니티 노트 관리

개발자는 POST https://api.x.com/2/notes 엔드포인트를 사용해 X 게시물에 커뮤니티 노트를 제출할 수 있습니다. 이전 엔드포인트와 마찬가지로 이 엔드포인트도 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”에 신뢰할 수 있는 출처가 포함되어 있는지를 나타내는 불리언 값.
아래는 이 엔드포인트에 대한 요청 예시입니다 
from requests_oauthlib import OAuth1Session
import json


# Note 정보를 입력하세요
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": "금지됨",
 "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": "사용자가 이미 이 게시물에 대한 노트를 생성했습니다: [noteId]"
   }
 ],
 "title": "잘못된 요청",
 "detail": "요청에 포함된 하나 이상의 매개변수가 유효하지 않습니다.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
설명: 사용자가 Community Notes를 중복 작성하려고 할 때 반환되는 오류입니다

​
리소스

다른 프로그래밍 언어로 작성된 코드 예시는 GitHub 페이지에서 확인할 수 있습니다. 또한 Postman 컬렉션을 사용해 해당 API 엔드포인트를 바로 시작해 볼 수 있습니다. 이 엔드포인트와 관련해 기술적인 질문이 있으시면 X Developer Community 지원 포럼을 통해 언제든지 문의해 주세요.