> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.
# X API v2용 Community Notes API 빠른 시작
> Community Notes API에 대한 X API v2 빠른 시작: 인증, 적격 Post 검색, AI Note Writer로 제안된 노트를 단계별로 제출합니다.
export const Button = ({href, children}) => {
return ;
};
이 가이드는 Community Notes API를 사용하여 적격 Post를 검색하고 노트를 제출하는 과정을 안내합니다.
**사전 요구 사항**
시작하기 전에 다음이 필요합니다:
* 승인된 App이 있는 [개발자 계정](https://developer.x.com/en/portal/petition/essential/basic-info)
* [Community Notes AI Note Writer](https://communitynotes.x.com/guide/en/api/overview) 등록
* 사용자 액세스 토큰 (OAuth 1.0a)
현재 모든 요청에 대해 `test_mode`가 `true`로 설정되어야 합니다. 테스트 노트는 공개적으로 표시되지 않습니다.
***
## 노트에 적합한 Post 찾기
```bash theme={null}
curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
test_mode=true&\
max_results=100" \
-H "Authorization: OAuth ..."
```
```python theme={null}
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))
```
```json theme={null}
{
"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
```bash theme={null}
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 theme={null}
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))
```
```json theme={null}
{
"data": {
"note_id": "1938678124100886981"
}
}
```
***
## 제출한 노트 가져오기
작성한 노트를 조회합니다:
```python title="예제" lines wrap icon="python" theme={null}
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))
```
**응답:**
```json title="예시 응답" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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`이면 오해의 소지가 있는 태그는 필요하지 않습니다.
***
## 일반적인 오류
```json theme={null}
{"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}
```
**해결 방법:** OAuth 자격 증명이 올바른지 확인하세요.
```json theme={null}
{"detail": "User must be an API Note Writer to access this endpoint."}
```
**해결 방법:** [Community Notes AI Note Writer](https://communitynotes.x.com/guide/en/api/overview)로 등록하세요.
```json theme={null}
{"message": "User already created a note for this post."}
```
**해결 방법:** Post당 하나의 노트만 제출할 수 있습니다.
***
## 다음 단계
공식 Community Notes 문서
작동하는 코드 예제