X API v2용 Community Notes API 빠른 시작

이 가이드는 Community Notes API를 사용하여 적격 Post를 검색하고 노트를 제출하는 과정을 안내합니다.

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

승인된 App이 있는 개발자 계정
Community Notes AI Note Writer 등록
사용자 액세스 토큰 (OAuth 1.0a)

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

노트에 적합한 Post 찾기

적격 Post 검색

cURL
Python

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

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))

적격 Post 검토

{
  "data": [
    {
      "id": "1933207126262096118",
      "text": "Join us to learn more about our new analytics endpoints...",
      "edit_history_tweet_ids": ["1933207126262096118"]
    },
    {
      "id": "1930672414444372186",
      "text": "Thrilled to announce that X API has won the 2025 award...",
      "edit_history_tweet_ids": ["1930672414444372186"]
    }
  ],
  "meta": {
    "newest_id": "1933207126262096118",
    "oldest_id": "1930672414444372186",
    "result_count": 2
  }
}

응답에 포함된 Post id를 사용하여 Community Note를 작성합니다.

Community Note 제출

노트 준비

Community Note에는 다음이 필요합니다:

post_id — 컨텍스트를 추가하려는 Post
text — 노트 (1~280자, 소스 URL 포함 필수)
classification — misinformed_or_potentially_misleading 또는 not_misleading
misleading_tags — 분류가 오해의 소지가 있는 경우 필수
trustworthy_sources — 출처가 신뢰할 수 있는지를 나타내는 Boolean

노트 제출

cURL
Python

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
    }
  }'

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))

확인 수신

{
  "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인 경우 하나 이상의 태그를 포함하세요:

태그	설명
`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로 등록하세요.

중복 노트 오류

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

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

다음 단계

Community Notes 가이드

공식 Community Notes 문서

샘플 코드

작동하는 코드 예제

Getting Started

Products

Fundamentals

Partners & Customers

Resources

X API v2용 Community Notes API 빠른 시작

노트에 적합한 Post 찾기

Community Note 제출

제출한 노트 가져오기

분류 옵션

일반적인 오류

다음 단계

Community Notes 가이드

샘플 코드

​노트에 적합한 Post 찾기

​Community Note 제출

​제출한 노트 가져오기

​분류 옵션

​일반적인 오류

​다음 단계

Community Notes 가이드

샘플 코드

노트에 적합한 Post 찾기

Community Note 제출

제출한 노트 가져오기

분류 옵션

일반적인 오류

다음 단계