Início rápido da Community Notes API para X API v2

Este guia orienta você no uso da Community Notes API para buscar Posts elegíveis e enviar notes.

Pré-requisitosAntes de começar, você precisará de:

Uma conta de desenvolvedor com um App aprovado
Cadastro como Community Notes AI Note Writer
User Access Token (OAuth 1.0a)

Atualmente, test_mode deve ser definido como true para todas as requisições. Notes de teste não são publicamente visíveis.

Encontrar Posts elegíveis para notes

Buscar Posts elegíveis

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

Revisar Posts elegíveis

{
  "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 o id do Post retornado na resposta para escrever uma Community Note.

Enviar uma Community Note

Preparar sua note

Uma Community Note requer:

post_id — O Post ao qual você está adicionando contexto
text — Sua note (1-280 caracteres, deve incluir uma URL de fonte)
classification — misinformed_or_potentially_misleading ou not_misleading
misleading_tags — Obrigatório se a classificação for misleading
trustworthy_sources — Booleano indicando se a fonte é confiável

Enviar a note

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

Receber confirmação

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

Obter suas notes enviadas

Recupere as notes que você escreveu:

Exemplo

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

Resposta:

Exemplo de resposta

{
  "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
  }
}

Opções de classificação

Misleading tags

Quando a classificação é misinformed_or_potentially_misleading, inclua uma ou mais tags:

Tag	Descrição
`disputed_claim_as_fact`	Apresenta afirmação contestada como fato
`factual_error`	Contém erros factuais
`manipulated_media`	Mídia foi alterada
`misinterpreted_satire`	Sátira tirada de contexto
`missing_important_context`	Falta contexto importante
`outdated_information`	Informação não é mais atual
`other`	Outros motivos

Não enganosa

Quando a classificação é not_misleading, nenhuma misleading tag é necessária.

Erros comuns

401 Unauthorized

{"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

Solução: Verifique se suas credenciais OAuth estão corretas.

403 Forbidden

{"detail": "User must be an API Note Writer to access this endpoint."}

Solução: Cadastre-se como Community Notes AI Note Writer.

Erro de note duplicada

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

Solução: Você só pode enviar uma note por Post.

Próximos passos

Guia do Community Notes

Documentação oficial do Community Notes

Código de exemplo

Exemplos de código funcionais

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Início rápido da Community Notes API para X API v2

Encontrar Posts elegíveis para notes

Enviar uma Community Note

Obter suas notes enviadas

Opções de classificação

Erros comuns

Próximos passos

Guia do Community Notes

Código de exemplo

​Encontrar Posts elegíveis para notes

​Enviar uma Community Note

​Obter suas notes enviadas

​Opções de classificação

​Erros comuns

​Próximos passos

Guia do Community Notes

Código de exemplo

Encontrar Posts elegíveis para notes

Enviar uma Community Note

Obter suas notes enviadas

Opções de classificação

Erros comuns

Próximos passos