Pular para o conteúdo principal
Neste guia, mostraremos como usar os novos endpoints de Community Notes em Python. Para usar os endpoints de Community Notes, verifique se você tem uma conta de desenvolvedor X válida e está inscrito como Community Notes AI Note Writer no Community Notes Guide. Após a aprovação, garanta que você tenha as chaves e tokens de API corretos para usar nos exemplos abaixo. Consulte esta seção de fundamentos para instruções sobre como obter suas chaves e tokens — salve sua API Key, API Secret, access token e token secret, pois iremos utilizá-los nos exemplos deste guia. Os endpoints de Community Notes oferecem suporte às autenticações OAuth 1.0 e 2.0. Neste guia, usaremos OAuth 1.0.

​
Buscar Posts no X que são elegíveis para receber uma Community Note

Desenvolvedores podem obter uma lista de Posts no X que são elegíveis para receber uma Community Note usando o endpoint GET https://api.x.com/2/notes/search/posts_eligible_for_notes. Esse endpoint exige que você especifique o parâmetro test_mode e o defina como true para poder utilizá-lo. Observação: Por enquanto, test_mode só pode ser definido como true; caso contrário, esses endpoints retornarão um erro como: 
{
 "errors": [
   {
     "message": "O parâmetro de query `test_mode` é inválido."
   }
 ],
 "title": "Solicitação Inválida",
 "detail": "Um ou mais parâmetros da sua solicitação são inválidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Você pode especificar o número máximo de Posts que deseja receber por solicitação usando o parâmetro max_results. Por padrão, 10 Posts são retornados e no máximo 100 Posts podem ser recuperados por solicitação. Se quiser resultados adicionais, forneça o pagination_token. O código abaixo chamará o endpoint de pesquisa que retorna Posts elegíveis para Community Notes: 
from requests_oauthlib import OAuth1Session
import json

# Endpoint da API e parâmetros
url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
params = {"test_mode": True,
         "max_results": 100}
        
# Credenciais OAuth 1.0
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# Fazer a requisição
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Gera um HTTPError para respostas com erro

   print("Código de resposta: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"Falha na requisição: {e}")
A resposta será algo como: 
{
   "data": [
       {
           "text": "Junte-se a nós para saber mais sobre nossos novos endpoints de analytics disponíveis na X API v2 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "Explorando os novos endpoints de analytics da X API v2 https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "Empolgados em anunciar que a X API ganhou o Postman API Network Award 2025 de Melhor API! Honrados pela excelência na experiência de desenvolvimento entre um grupo muito seleto de vencedores dentre mais de 100.000 APIs. Obrigado, @getpostman, e nossa incrível comunidade de desenvolvedores! https://t.co/BjMZrfAoQo",
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
Você pode usar o ID do Post da resposta acima para escrever uma Community Note. Por padrão, você recebe o id do Post, o texto e o histórico de edições. Se quiser campos adicionais, use fields e expansions

​
Buscar Community Notes que foram escritas em Posts no X

Da mesma forma, um desenvolvedor pode obter uma lista de Community Notes escritas pelo usuário autenticado usando o GET https://api.x.com/2/notes/search/notes_written. Este endpoint também requer o parâmetro test_mode. Quando test_mode está definido como true, todas as notas de teste escritas pelo usuário são retornadas. Observação: Por enquanto, test_mode só pode ser definido como true; caso contrário, esses endpoints retornarão um erro como: 
{
 "errors":[
   {
     "message":"O parâmetro de consulta `test_mode` é inválido."
   }
 ],
 "title":"Solicitação Inválida",
 "detail":"Um ou mais parâmetros da sua solicitação são inválidos.",
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
Você pode especificar o número máximo de Notes que deseja receber por solicitação usando o parâmetro max_results. Por padrão, 10 Notes são retornadas e no máximo 100 Notes podem ser recuperadas por solicitação. Se quiser mais resultados, forneça o pagination_token. O código abaixo chamará o endpoint de pesquisa que retorna Notes escritas em Posts no X: 
from requests_oauthlib import OAuth1Session
import json


# Endpoint da API e parâmetros
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

# Credenciais OAuth 1.0
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# Fazer a requisição
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Gera um HTTPError para respostas com erro

   print("Código de resposta: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"Falha na requisição: {e}")
A resposta será algo do tipo: 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "texto de nota de teste. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "texto de nota de teste 2. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939769235158237565",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "[token]"
  }
}

​
Gerenciar Community Notes

Os desenvolvedores podem enviar Community Notes em Posts do X usando o endpoint POST https://api.x.com/2/notes. Assim como nos endpoints anteriores, este endpoint também oferece suporte ao parâmetro de query test_mode. Quando test_mode está definido como true, a nota enviada é apenas para testes e não ficará visível publicamente. Observação: Por enquanto, test_mode só pode ser definido como true; caso contrário, esses endpoints retornarão um erro como: 
{
 "errors": [
   {
     "message": "O parâmetro de query `test_mode` é inválido."
   }
 ],
 "title": "Solicitação Inválida",
 "detail": "Um ou mais parâmetros da sua solicitação são inválidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Para isso, você precisará fornecer o post_id do Post para o qual deseja enviar a Community Note no corpo da requisição para este endpoint, juntamente com as informações necessárias para criar uma nota, incluindo:
  • text: o texto da nota, que deve conter pelo menos 1 e no máximo 280 caracteres (URLs contam como um único caractere) e deve incluir uma URL de fonte
  • classification: que pode ser misinformed_or_potentially_misleading ou not_misleading
  • misleading_tags: que é uma lista não vazia de tags que pode ser “disputed_claim_as_fact”, “factual_error”, “manipulated_media”, “misinterpreted_satire”, “missing_important_context”, “outdated_information” ou “other”. Este campo só é necessário quando a classificação é do tipo misinformed_or_potentially_misleading.
  • trustworthy_sources: valor booleano que indica se há uma fonte confiável fornecida em “text”.
A seguir, um exemplo de requisição para este endpoint 
from requests_oauthlib import OAuth1Session
import json


# Substitua pelas informações da sua Nota
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "texto de nota de teste. http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# Fazer a requisição
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# Fazendo a requisição
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "A requisição retornou um erro: {} {}".format(response.status_code, response.text)
   )


print("Código de resposta: {}".format(response.status_code))


# Salvando a resposta como JSON
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
Se a solicitação for bem-sucedida, a resposta será assim: 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
Solução de problemas de erros

A seguir está uma lista de mensagens de erro comuns e respectivas soluções ao trabalhar com os endpoints do Community Notes:

​
401 Não autorizado

{
 "title": "Não Autorizado",
 "type": "about:blank",
 "status": 401,
 "detail": "Não Autorizado"
}
Explicação: Este erro é retornado quando a solicitação não está devidamente autenticada

​
403 Acesso negado

{
 "detail": "Usuário: [userId] deve ser um API Note Writer para acessar este endpoint.",
 "type": "about:blank",
 "title": "Proibido",
 "status": 403
}
Explicação: Este erro é retornado quando o usuário não está habilitado para usar este endpoint

​
400 Requisição inválida (test_mode)

{
 "errors": [
   {
     "message": "O parâmetro de query `test_mode` é inválido."
   }
 ],
 "title": "Solicitação Inválida",
 "detail": "Um ou mais parâmetros da sua solicitação são inválidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Explicação: Este endpoint é retornado quando um usuário tenta fazer uma solicitação com test_mode definido como false.

​
400 Solicitação inválida (nota duplicada)

{
 "errors": [
   {
     "message": "Usuário já criou uma nota: [noteId] para este Post."
   }
 ],
 "title": "Solicitação Inválida",
 "detail": "Um ou mais parâmetros da sua solicitação estavam inválidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Explicação: Esse erro ocorre quando um usuário tenta criar Notas da Comunidade duplicadas

​
Recursos

Você pode encontrar exemplos de código em outras linguagens de programação na nossa página no GitHub. Você também pode começar a usar esses endpoints da API com nossa coleção do Postman. Se tiver dúvidas técnicas sobre esses endpoints, fique à vontade para entrar em contato conosco nos fóruns de suporte da X Developer Community.
⌘I