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 Twitter unchanged.

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, or remove your rating. Use BirdwatchCreateRating and BirdwatchDeleteRating.

helpfulness is "Helpful", "SomewhatHelpful" or "NotHelpful". emusks sends helpfulTags unless the rating is NotHelpful, and notHelpfulTags unless it is Helpful, matching x.com's rating form. A BirdwatchError result throws with its error_code on error.code.

await client.notes.rate(noteId, {
  tweetId,
  helpfulness: "Helpful",
  helpfulTags: ["GoodSources", "ImportantContext"],
});

Helpful tags: GoodSources, Clear, AddressesClaim, ImportantContext, UnbiasedLanguage, Other.

Not helpful tags: NoSources, IrrelevantSources, Incorrect, OpinionSpeculation, Unclear, MissingKeyPoints, Rude (argumentative or biased), NoteNotNeeded (only valid on notes that call the post misleading), TwitterViolationAny (spam, harassment or abuse), Other.

source defaults to "BirdwatchPostDetail" and platform to "BirdwatchWeb". Any other keys in rating, plus rating.variables, are merged into the mutation variables unchanged, so a hand-built { tweet_id, data_v2 } still works.

The viewer's current rating comes back on each note from forTweet as note.rating.data_v2.

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.