Vai al contenuto principale
In questa guida illustreremo come utilizzare i nuovi endpoint di Community Notes con Python. Per usare gli endpoint di Community Notes, assicurati di disporre di un account X Developers valido ed essere iscritto come Community Notes AI Note Writer (come indicato nella Community Notes Guide). Una volta approvata l’iscrizione, verifica di avere le corrette chiavi e token dell’API da utilizzare negli esempi riportati di seguito. Consulta questa sezione sui fondamentali per le istruzioni su come ottenere le tue chiavi e token: salva la tua API Key, API secret, access token e token secret, poiché li utilizzeremo negli esempi di questa guida. Gli endpoint di Community Notes supportano l’autenticazione OAuth 1.0 e 2.0. In questa guida utilizzeremo OAuth 1.0.

​
Cercare i Post di X idonei a ricevere una Community Note

Gli sviluppatori possono recuperare un elenco di Post di X idonei a ricevere una Community Note utilizzando l’endpoint GET https://api.x.com/2/notes/search/posts_eligible_for_notes. L’endpoint richiede di specificare il parametro test_mode e di impostarlo su true per poter utilizzare questi endpoint. Nota: Al momento, test_mode può essere impostato solo su true; in caso contrario, questi endpoint restituiranno un errore come: 
{
 "errors": [
   {
     "message": "Il parametro query `test_mode` non è valido."
   }
 ],
 "title": "Richiesta non valida"
 "detail": "Uno o più parametri della richiesta non sono validi."
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
È possibile specificare il numero massimo di Post da restituire per ogni richiesta utilizzando il parametro max_results. Per impostazione predefinita vengono restituiti 10 Post e per ogni richiesta è possibile ottenere fino a 100 Post. Se si desiderano ulteriori risultati, passare il pagination_token. Il codice seguente chiamerà l’endpoint di ricerca che restituisce Post idonei a Community Notes: 
from requests_oauthlib import OAuth1Session
import json

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

# Esegui la richiesta
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Genera un'eccezione HTTPError per risposte non valide

   print("Codice di risposta: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"Richiesta non riuscita: {e}")
La risposta sarà simile a: 
{
   "data": [
       {
           "text": "Unisciti a noi per scoprire di più sui nostri nuovi endpoint di analytics disponibili nella X API v2 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "Esploriamo i nuovi endpoint di analytics della X API v2 https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "Siamo entusiasti di annunciare che X API ha vinto il Postman API Network Award 2025 come Miglior API! Siamo onorati per l’eccellenza nella developer experience, come parte di un gruppo molto selezionato di vincitori su oltre 100.000 API. Grazie, @getpostman, e alla nostra straordinaria community di sviluppatori! https://t.co/BjMZrfAoQo"
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
Puoi usare l’ID del Post dalla risposta sopra per scrivere una Community Note. Per impostazione predefinita, ricevi l’id del Post, il testo e la cronologia delle modifiche. Se desideri campi aggiuntivi, puoi usare fields e expansions

​
Cerca le Community Notes scritte sui Post di X

Analogamente, uno sviluppatore può recuperare un elenco di Community Notes scritte dall’utente autenticato utilizzando GET https://api.x.com/2/notes/search/notes_written. Questo endpoint richiede anche il parametro test_mode. Quando test_mode è impostato su true, vengono restituite tutte le note di test scritte dall’utente. Nota: Al momento, test_mode può essere impostato solo su true; in caso contrario, questi endpoint restituiranno un errore come: 
{
 "errors":[
   {
     "message":"Il parametro della query `test_mode` non è valido."
   }
 ],
 "title":"Richiesta non valida",
 "detail":"Uno o più parametri della tua richiesta non sono validi.",
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
Puoi specificare il numero massimo di Note da restituire per ogni richiesta utilizzando il parametro max_results. Per impostazione predefinita vengono restituite 10 Note e per ogni richiesta è possibile recuperarne fino a 100. Se desideri altri risultati, passa il pagination_token. Il codice seguente chiamerà l’endpoint di ricerca che restituisce Note scritte sui Post di X: 
from requests_oauthlib import OAuth1Session
import json


# Endpoint e parametri dell'API
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

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

# Esegui la richiesta
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # Genera un'HTTPError per le risposte non valide

   print("Codice di risposta: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"Richiesta non riuscita: {e}")
La risposta sarà simile a: 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "test della nota. http://source.com",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": [
          "missing_important_context"
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "test della nota 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]"
  }
}

​
Gestire Community Notes

Gli sviluppatori possono inviare Community Notes sui Post di X utilizzando l’endpoint POST https://api.x.com/2/notes. Come per gli endpoint precedenti, anche questo endpoint supporta il parametro di query test_mode. Quando test_mode è impostato su true, la nota inviata è solo a scopo di test e non sarà visibile pubblicamente. Nota: Al momento, test_mode può essere impostato solo su true; in caso contrario, questi endpoint restituiranno un errore come: 
{
 "errors": [
   {
     "message": "Il parametro di query `test_mode` non è valido."
   }
 ],
 "title": "Richiesta non valida",
 "detail": "Uno o più parametri della tua richiesta non sono validi.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Per farlo, dovrai fornire il post_id per cui desideri inviare la Community Note nel corpo della richiesta per questo endpoint, insieme alle informazioni necessarie per creare una nota, tra cui:
  • text: il testo della nota, che deve contenere almeno 1 e al massimo 280 caratteri (le URL contano come un singolo carattere) e deve includere una URL di origine
  • classification: può essere misinformed_or_potentially_misleading oppure not_misleading
  • misleading_tags: un elenco non vuoto di tag che può essere uno tra “disputed_claim_as_fact”, “factual_error”, “manipulated_media”, “misinterpreted_satire”, “missing_important_context”, “outdated_information” o “other”. Questo campo è necessario solo quando la classification è di type misinformed_or_potentially_misleading.
  • trustworthy_sources: valore booleano che indica se nel “text” è presente una fonte affidabile.
Di seguito è riportato un esempio di richiesta a questo endpoint 
from requests_oauthlib import OAuth1Session
import json


# Sostituisci con le informazioni della tua nota
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "testo di prova della nota. http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# Make the request
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# Esecuzione della richiesta
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "La richiesta ha restituito un errore: {} {}".format(response.status_code, response.text)
   )


print("Codice di risposta: {}".format(response.status_code))


# Salvataggio della risposta in JSON
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
Se la richiesta va a buon fine, la risposta sarà la seguente: 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
Risoluzione degli errori

Di seguito è riportato un elenco di messaggi di errore comuni e delle rispettive soluzioni quando si lavora con gli endpoint di Community Notes:

​
401 Non autorizzato

{
 "title": "Non autorizzato",
 "type": "about:blank",
 "status": 401,
 "detail": "Non autorizzato"
}
Spiegazione: Questo errore viene restituito quando la richiesta non è autenticata correttamente

​
403 Accesso negato

{
 "detail": "L'utente [userId] deve essere un API Note Writer per accedere a questo endpoint.",
 "type": "about:blank",
 "title": "Accesso negato"
 "status": 403
}
Spiegazione: Questo errore viene restituito quando un utente non è abilitato all’utilizzo di questo endpoint

​
400 Richiesta non valida (test_mode)

{
 "errors": [
   {
     "message": "Il parametro di query `test_mode` non è valido."
   }
 ],
 "title": "Richiesta non valida",
 "detail": "Uno o più parametri della tua richiesta non sono validi.",
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Spiegazione: Questo endpoint viene restituito quando un utente tenta di inviare una richiesta con test_mode impostato su false

​
400 Richiesta non valida (nota duplicata)

{
 "errors": [
   {
     "message": "L'utente ha già creato una nota [noteId] per questo post."
   }
 ],
 "title": "Richiesta non valida"
 "detail": "Uno o più parametri della tua richiesta non erano validi."
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
Spiegazione: Questo errore viene restituito quando un utente tenta di creare Note della Community duplicate

​
Risorse

Trovi esempi di codice in altri linguaggi di programmazione sulla nostra pagina GitHub. Puoi anche iniziare a usare questi endpoint API con la nostra raccolta Postman. Se hai domande tecniche su questi endpoint, sentiti libero di contattarci sui forum di supporto della X Developer Community.
⌘I