> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 빠른 시작

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

export const Button = ({href, children}) => {
  return <div className="not-prose group">
    <a href={href}>
      <button className="flex items-center space-x-2.5 py-1 px-4 bg-primary-dark dark:bg-white text-white dark:text-gray-950 rounded-full group-hover:opacity-[0.9] font-medium">
        <span>
          {children}
        </span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

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

<Note>
  **사전 준비 사항**

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

  * 승인된 App이 포함된 [개발자 계정](https://developer.x.com/en/portal/petition/essential/basic-info)
  * [Community Notes AI Note Writer](https://communitynotes.x.com/guide/en/api/overview)로 등록되어 있을 것
  * 사용자 액세스 토큰(User Access Token, OAuth 1.0a)
</Note>

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

***

<div id="find-posts-eligible-for-notes">
  ## 노트 대상 포스트 찾기
</div>

<Steps>
  <Step title="노트 대상 포스트 검색" icon="magnifying-glass">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
        test_mode=true&\
        max_results=100" \
          -H "Authorization: OAuth ..."
        ```
      </Tab>

      <Tab title="Python">
        ```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))
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="노트 대상 포스트 검토" icon="eye">
    ```json theme={null}
    {
      "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를 작성하세요.
  </Step>
</Steps>

***

<div id="submit-a-community-note">
  ## 커뮤니티 노트 제출하기
</div>

<Steps>
  <Step title="노트 준비" icon="pen">
    커뮤니티 노트를 제출하려면 다음 항목이 필요합니다:

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

  <Step title="노트 제출" icon="paper-plane">
    <Tabs>
      <Tab title="cURL">
        ```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
            }
          }'
        ```
      </Tab>

      <Tab title="Python">
        ```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))
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="확인 응답 받기" icon="check">
    ```json theme={null}
    {
      "data": {
        "note_id": "1938678124100886981"
      }
    }
    ```
  </Step>
</Steps>

***

<div id="get-your-submitted-notes">
  ## 제출한 노트 조회
</div>

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

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

***

<div id="classification-options">
  ## 분류 옵션
</div>

<AccordionGroup>
  <Accordion title="오해를 불러일으키는 태그">
    분류가 `misinformed_or_potentially_misleading`인 경우, 하나 이상의 태그를 포함하세요:

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

  <Accordion title="오해의 소지가 없음">
    분류가 `not_misleading`인 경우, 오해를 불러일으키는 태그는 필요하지 않습니다.
  </Accordion>
</AccordionGroup>

***

<div id="common-errors">
  ## 자주 발생하는 오류
</div>

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}
    ```

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

  <Accordion title="403 Forbidden">
    ```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)로 등록하세요.
  </Accordion>

  <Accordion title="Duplicate note error">
    ```json theme={null}
    {"message": "User already created a note for this post."}
    ```

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

***

<div id="next-steps">
  ## 다음 단계
</div>

<CardGroup cols={2}>
  <Card title="Community Notes 가이드" icon="book" href="https://communitynotes.x.com/guide/en/api/overview">
    공식 Community Notes 문서
  </Card>

  <Card title="샘플 코드" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    실행 가능한 코드 예시
  </Card>
</CardGroup>