Saltar al contenido principal
En esta guía, le mostraremos cómo usar los nuevos endpoints de Community Notes con Python. Para usar los endpoints de Community Notes, asegúrese de tener una cuenta válida de X Developers y de estar inscrito como Community Notes AI Note Writer en la Community Notes Guide. Una vez aprobado, asegúrese de contar con las keys and tokens de la API correctas para usar en los ejemplos que se incluyen a continuación. Consulte esta sección de fundamentos para obtener instrucciones sobre cómo conseguir sus keys and tokens; guarde su API Key, API Secret, access token y token secret, ya que los usaremos en los ejemplos de esta guía. Los endpoints de Community Notes admiten autenticación OAuth 1.0 y 2.0. En esta guía, usaremos OAuth 1.0.

​
Buscar Posts de X que sean aptos para recibir una Community Note

Los desarrolladores pueden obtener una lista de Posts de X aptos para recibir una Community Note mediante el endpoint GET https://api.x.com/2/notes/search/posts_eligible_for_notes. Este endpoint requiere especificar el parámetro test_mode y establecerlo en true para poder usar estos endpoints. Nota: Por ahora, test_mode solo puede establecerse en true; de lo contrario, estos endpoints devolverán un error como: 
{
 "errors": [
   {
     "message": "El parámetro query `test_mode` no es válido."
   }
 ],
 "title": "Solicitud no válida"
 "detail": "Uno o más parámetros de su solicitud no son válidos."
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Puede especificar la cantidad máxima de Posts que desea que se devuelvan por solicitud mediante el parámetro max_results. De forma predeterminada, se devuelven 10 Posts y se puede recuperar un máximo de 100 Posts por solicitud. Si desea más resultados, incluya el pagination_token. El siguiente código llamará al endpoint de búsqueda que devuelve Posts aptos para Community Notes: 
from requests_oauthlib import OAuth1Session
import json

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

# Realizar la solicitud
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Genera un HTTPError para respuestas con error

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

except Exception as e:
   print(f"Error en la solicitud: {e}")
La respuesta será algo como lo siguiente: 
{
   "data": [
       {
           "text": "Únete a nosotros para conocer más sobre nuestros nuevos endpoints de analítica disponibles en la X API v2 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "Explorando los nuevos endpoints de analítica de la X API v2 https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "Nos complace anunciar que X API ha ganado el Postman API Network Award 2025 a la Mejor API. Un honor que reconoce la excelencia en la experiencia para desarrolladores, otorgado a un grupo muy selecto de ganadores entre más de 100,000 APIs. ¡Gracias, @getpostman, y a nuestra increíble comunidad de desarrolladores! https://t.co/BjMZrfAoQo"
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
Puedes usar el ID de Post de la respuesta anterior para escribir una Community Note. De forma predeterminada, obtendrás el ID de Post, el texto y el historial de edición. Si quieres campos adicionales, puedes usar fields y expansions

​
Buscar Notas de la Comunidad que se han escrito en Posts de X

De manera similar, un desarrollador puede obtener una lista de Notas de la Comunidad que haya escrito el usuario autenticado usando GET https://api.x.com/2/notes/search/notes_written. Este endpoint también requiere el parámetro test_mode. Cuando test_mode se establece en true, se devuelven todas las notas de prueba escritas por el usuario. Nota: Por ahora, test_mode solo se puede establecer en true; de lo contrario, estos endpoints devolverán un error como: 
{
 "errors":[
   {
     "message":"El parámetro de query `test_mode` no es válido."
   }
 ],
 "title":"Solicitud no válida",
 "detail":"Uno o más parámetros de tu solicitud no son válidos.",
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
Puede especificar el número máximo de Notes que desea recibir por solicitud usando el parámetro max_results. De forma predeterminada, se devuelven 10 Notes y se puede recuperar un máximo de 100 Notes por solicitud. Si desea más resultados, pase el pagination_token. El siguiente código llamará al endpoint de búsqueda que devuelve Notes escritas en Posts de X: 
from requests_oauthlib import OAuth1Session
import json


# Endpoint de la API y parámetros
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

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

# Realizar la solicitud
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Lanza un HTTPError para respuestas erróneas

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

except Exception as e:
   print(f"Error en la solicitud: {e}")
La respuesta será algo como: 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "texto de nota de prueba. http://source.com",
        "classification": "desinformación_o_potencialmente_engañoso",
        "misleading_tags": [
          "falta_contexto_importante"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "texto de nota de prueba 2. http://source.com",
        "classification": "desinformación_o_potencialmente_engañoso",
        "misleading_tags": [
          "falta_contexto_importante"
        ],
        "post_id": "1939769235158237565",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "[token]"
  }
}

​
Administrar Community Notes

Los desarrolladores pueden enviar Community Notes en Posts de X mediante el endpoint POST https://api.x.com/2/notes. Al igual que los endpoints anteriores, este endpoint también admite el parámetro de query test_mode. Cuando test_mode se establece en true, la nota enviada es solo para pruebas y no será visible públicamente. Nota: Por ahora, test_mode solo se puede establecer en true; de lo contrario, estos endpoints devolverán un error como: 
{
 "errors": [
   {
     "message": "El parámetro de query `test_mode` no es válido."
   }
 ],
 "title": "Solicitud no válida"
 "detail": "Uno o más parámetros de tu solicitud no son válidos."
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Para hacerlo, deberá proporcionar el post_id para el que desea enviar la Community Note en el cuerpo de la solicitud para este endpoint, junto con la información requerida para crear una nota, incluidas:
  • text: el texto de la nota, que debe contener al menos 1 y como máximo 280 caracteres (las URL cuentan como un solo carácter) y debe incluir una URL de fuente
  • classification: que puede ser misinformed_or_potentially_misleading o not_misleading
  • misleading_tags: que es una lista no vacía de etiquetas que puede ser cualquiera de “disputed_claim_as_fact”, “factual_error”, “manipulated_media”, “misinterpreted_satire”, “missing_important_context”, “outdated_information” o “other”. Este campo solo se requiere cuando la clasificación es de type misinformed_or_potentially_misleading.
  • trustworthy_sources: valor booleano para indicar si se proporciona una fuente confiable en “text”.
A continuación se muestra un ejemplo de solicitud a este endpoint 
from requests_oauthlib import OAuth1Session
import json


# Sustituye con la información de tu Nota
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "texto de nota de prueba. http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# Realiza la solicitud
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# Realizando la solicitud
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "La solicitud devolvió un error: {} {}".format(response.status_code, response.text)
   )


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


# Guardar la respuesta como JSON
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
Si la solicitud se realiza correctamente, la respuesta tendrá el siguiente aspecto: 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
Solución de problemas de errores

A continuación se presenta una lista de mensajes de error comunes y sus resoluciones al trabajar con los endpoints de Community Notes:

​
401 No autorizado

{
 "title": "No autorizado",
 "type": "about:blank",
 "status": 401,
 "detail": "No autorizado"
}
Explicación: Este error se devuelve cuando la solicitud no está correctamente autenticada

​
403 Prohibido

{
 "detail": "El usuario [userId] debe ser un autor de notas de la API para acceder a este endpoint.",
 "type": "about:blank",
 "title": "Prohibido",
 "status": 403
}
Explicación: Este error se devuelve cuando un usuario no está habilitado para usar este endpoint

​
400 Solicitud inválida (test_mode)

{
 "errors": [
   {
     "message": "El parámetro de query `test_mode` no es válido."
   }
 ],
 "title": "Solicitud no válida",
 "detail": "Uno o más parámetros de tu solicitud no son válidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Explicación: Este endpoint se devuelve cuando un usuario intenta realizar una solicitud con test_mode configurado en false

​
400 Solicitud inválida (Nota duplicada)

{
 "errors": [
   {
     "message": "El usuario ya creó una nota: [noteId] para este Post."
   }
 ],
 "title": "Solicitud no válida",
 "detail": "Uno o más parámetros de su solicitud no fueron válidos.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Explicación: Este error se devuelve cuando un usuario intenta crear notas de la comunidad duplicadas

​
Recursos

Puedes encontrar ejemplos de código en otros lenguajes de programación en nuestra página de GitHub. También puedes comenzar con estos endpoints de la API usando nuestra colección de Postman. Si tienes alguna pregunta técnica sobre estos endpoints, no dudes en comunicarte con nosotros en los foros de soporte de la X Developer Community.
⌘I