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 claves y los tokens de API correctos para utilizarlos en los ejemplos que se indican a continuación. Consulte esta sección de fundamentos para obtener instrucciones sobre cómo obtener sus claves y 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 publicaciones de X que sean aptas para recibir una Nota de la Comunidad

Los desarrolladores pueden obtener una lista de publicaciones de X que sean aptas para recibir una Nota de la Comunidad usando el endpoint GET https://api.x.com/2/notes/search/posts_eligible_for_notes. El endpoint requiere que especifiques el parámetro test_mode y lo configures en true para poder usar estos endpoints. Nota: Por ahora, test_mode solo puede configurarse en true; de lo contrario, estos endpoints devolverán un error como: 
{
 "errors": [
   {
     "message": "El parámetro de consulta `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 la cantidad máxima de Posts que desea obtener por solicitud usando 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 resultados adicionales, pase 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 de la API y parámetros
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 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"La solicitud falló: {e}")
La respuesta será algo como esto: 
{
   "data": [
       {
           "text": "Únete para conocer más sobre nuestros nuevos endpoints de analíticas disponibles en X API v2 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "Explorando los nuevos endpoints de analíticas de X API v2 https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "¡Emocionados de anunciar que X API ha ganado el premio Postman API Network Award 2025 a la Mejor API! Reconocidos por la excelencia en experiencia de desarrollo dentro de 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 del Post de la respuesta anterior para escribir una Nota de la comunidad. De forma predeterminada, obtienes el id del Post, el texto y el historial de ediciones. Si quieres campos adicionales, puedes usar fields y expansions.

​
Buscar Notas de la comunidad escritas en Publicaciones de X

De manera similar, un desarrollador puede obtener una lista de Notas de la comunidad escritas por el usuario autenticado usando la solicitud 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 consulta `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 Notes que desea que se devuelvan 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 resultados adicionales, pase el pagination_token. El siguiente código llamará al endpoint de búsqueda que devuelve Notes escritas en X Posts: 
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()  # Genera 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"La solicitud falló: {e}")
La respuesta será algo como: 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "texto de nota de prueba. 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 prueba 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]"
  }
}

​
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 consulta 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 consulta `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"
}
Para hacerlo, deberá proporcionar el post_id del Post para el que desea enviar la Nota de la comunidad en el cuerpo de la solicitud a este endpoint, junto con la información requerida para crear una nota, incluidos:
  • 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, y puede ser cualquiera de “disputed_claim_as_fact”, “factual_error”, “manipulated_media”, “misinterpreted_satire”, “missing_important_context”, “outdated_information” o “other”. Este campo solo es necesario cuando la clasificación es del tipo misinformed_or_potentially_misleading.
  • trustworthy_sources: valor booleano que indica si se proporciona una fuente confiable en “text”.
A continuación se muestra un ejemplo de solicitud para este endpoint 
from requests_oauthlib import OAuth1Session
import json


# Reemplaza 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 será la siguiente: 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
Solución de problemas

A continuación encontrarás una lista de mensajes de error comunes y sus soluciones 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á autenticada correctamente.

​
403 Forbidden

{
 "detail": "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 el usuario no está habilitado para usar este endpoint

​
400 Solicitud inválida (test_mode)

{
 "errors": [
   {
     "message": "El parámetro de consulta `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 establecido 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 son 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 empezar con estos endpoints de la API usando nuestra colección de Postman. Si tienes alguna pregunta técnica sobre estos endpoints, no dudes en ponerte en contacto con nosotros en los foros de soporte de X Developer Community.