Community Notes

Read and contribute to Community Notes (the system formerly called Birdwatch). All read methods work on any account; contributing requires an enrolled Community Notes account.

WARNING

The write methods (create, rate, appeal, alias/settings, admin) require an enrolled Community Notes account. notes.create takes data_v1, the note content payload (text, classification, and believability/misleading tags); emusks forwards it to X unchanged. The write paths were not executed end-to-end during testing.

Reading

notes.forTweet(tweetId)

Get the Community Notes on a tweet. Uses the GraphQL BirdwatchFetchNotes query.

const result = await client.notes.forTweet("1962559135531504125");

notes.get(noteId)

Fetch a single note by id. Uses the GraphQL BirdwatchFetchOneNote query.

const note = await client.notes.get("2062655324432240669");
console.log(note.appeal_status, note.birdwatch_profile?.alias);

notes.translation(noteId, opts?)

Get a note's translation. Uses the GraphQL BirdwatchFetchNoteTranslation query.

notes.globalTimeline(opts?)

The global Community Notes timeline (recently noted tweets). Uses the GraphQL BirdwatchFetchGlobalTimeline query.

const { viewer } = await client.notes.globalTimeline();

notes.myProfile() / notes.profile(alias) / notes.contributorNotes(alias, opts?)

Your own Community Notes profile, another contributor's profile by alias, and a contributor's notes. Use BirdwatchFetchAuthenticatedUserProfile, BirdwatchFetchBirdwatchProfile, and BirdwatchFetchContributorNotesSlice.

const me = await client.notes.myProfile();
const them = await client.notes.profile("logical-raccoon");
const theirNotes = await client.notes.contributorNotes("logical-raccoon");

notes.batSignal(tweetId)

Whether a tweet has an open request for a note ("bat signal"). Uses BirdwatchFetchBatSignal.

notes.canBeMediaNote(tweetId) / notes.mediaMatches(tweetId, opts?) / notes.prominentMediaMatches(tweetId, opts?)

Media-note eligibility and notes matched to the same media. Use BirdwatchFetchCanTweetBeMediaNote, BirdwatchFetchMediaMatchSlice, BirdwatchFetchProminentMediaMatchSlice.

notes.sourceLinks(tweetId, opts?) / notes.sourceLinkTweet(tweetId)

Source links cited in notes for a tweet. Use BirdwatchFetchSourceLinkSlice and BirdwatchFetchSourceLinkTweet.

notes.clusterData(tweetId) / notes.authenticatedMatch(noteId) / notes.suggestionFeedback(suggestionId)

Cluster data, your match status for a note, and suggestion feedback. Use BirdwatchFetchClusterData, BirdwatchFetchAuthenticatedBirdwatchMatchSlice, BirdwatchFetchSuggestionFeedbackOverview.

notes.aliasOptions() / notes.aliasStatus() / notes.signUpEligibility() / notes.publicData()

Alias self-select options/status, your sign-up eligibility, and the public data file bundle. Use BirdwatchFetchAliasSelfSelectOptions, BirdwatchFetchAliasSelfSelectStatus, BirdwatchFetchSignUpEligiblity, BirdwatchFetchPublicData.

const elig = await client.notes.signUpEligibility();
console.log(elig.eligible);

Contributing

notes.create(tweetId, dataV1, opts?)

Write a note on a tweet. Uses the GraphQL BirdwatchCreateNote mutation. dataV1 is the note content payload.

await client.notes.create(tweetId, dataV1);

notes.remove(noteId)

Delete one of your notes. Uses BirdwatchDeleteNote.

notes.rate(noteId, rating?) / notes.deleteRating(noteId)

Rate a note helpful/not-helpful, or remove your rating. Use BirdwatchCreateRating and BirdwatchDeleteRating. rating is merged into the mutation variables.

await client.notes.rate(noteId, { helpful_tags: ["Clear", "Informative"] });

notes.appeal(noteId, opts?)

Appeal a note's status. Uses BirdwatchCreateAppeal.

notes.request(tweetId) / notes.deleteRequest(tweetId)

Request a note on a tweet (raise the "bat signal"), or withdraw it. Use BirdwatchCreateBatSignal and BirdwatchDeleteBatSignal.

notes.selectAlias(opts?) / notes.editUserSettings(params) / notes.editNotificationSettings(params) / notes.acknowledgeEarnOut()

Manage your contributor alias and settings. Use BirdwatchAliasSelect, BirdwatchEditUserSettings, BirdwatchEditNotificationSettings, BirdwatchProfileAcknowledgeEarnOut.

notes.admitUser(opts?) / notes.removeUser(opts?)

Admin moderation actions (require the relevant permissions). Use BirdwatchAdmitUser and BirdwatchRemoveUser.