Skip to main content

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.

This guide walks you through using the Community Notes API to search for eligible Posts and submit notes.
PrerequisitesBefore you begin, you’ll need:
Currently, test_mode must be set to true for all requests. Test notes are not publicly visible.

​
Find Posts eligible for notes

Search for eligible Posts

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

Review eligible Posts

{
  "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
  }
}
Use the Post id from the response to write a Community Note.

​
Submit a Community Note

Prepare your note

A Community Note requires:
  • post_id — The Post you’re adding context to
  • text — Your note (1-280 characters, must include a source URL)
  • classification — Either misinformed_or_potentially_misleading or not_misleading
  • misleading_tags — Required if classification is misleading
  • trustworthy_sources — Boolean indicating if source is trustworthy

Submit the note

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

Receive confirmation

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

​
Get your submitted notes

Retrieve notes you’ve written: 
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))
Response: 
{
  "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
  }
}

​
Classification options

When classification is misinformed_or_potentially_misleading, include one or more tags:
TagDescription
disputed_claim_as_factPresents disputed claim as fact
factual_errorContains factual errors
manipulated_mediaMedia has been altered
misinterpreted_satireSatire taken out of context
missing_important_contextLacks key context
outdated_informationInformation is no longer current
otherOther reasons
When classification is not_misleading, no misleading tags are required.

​
Common errors

{"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}
Resolution: Check your OAuth credentials are correct.
{"detail": "User must be an API Note Writer to access this endpoint."}
Resolution: Enroll as a Community Notes AI Note Writer.
{"message": "User already created a note for this post."}
Resolution: You can only submit one note per Post.

​
Next steps

Community Notes Guide

Official Community Notes documentation

Sample code

Working code examples