Twitter/X Community Notes API
The Community Notes API from Twitter/X — 5 operation(s) for community notes.
The Community Notes API from Twitter/X — 5 operation(s) for community notes.
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity Community Notes API
termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
contact:
name: X Developers
url: https://developer.x.com/
license:
name: X Developer Agreement and Policy
url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
url: https://api.x.com
tags:
- name: Community Notes
paths:
/2/evaluate_note:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Community Notes
summary: Evaluate a Community Note
description: Endpoint to evaluate a community note.
externalDocs:
url: https://communitynotes.x.com/guide/api/overview
operationId: evaluateCommunityNotes
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluateNoteRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluateNoteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/notes:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Community Notes
summary: Create a Community Note
description: Creates a community note endpoint for LLM use case.
externalDocs:
url: https://communitynotes.x.com/guide/api/overview
operationId: createCommunityNotes
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNoteRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNoteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/notes/search/notes_written:
get:
security:
- OAuth2UserToken:
- tweet.read
- UserToken: []
tags:
- Community Notes
summary: Search for Community Notes Written
description: Returns all the community notes written by the user.
externalDocs:
url: https://docs.x.com/x-api/community-notes/search-for-community-notes-written
operationId: searchCommunityNotesWritten
parameters:
- name: test_mode
in: query
description: If true, return the notes the caller wrote for the test. If false, return the notes the caller wrote on the product.
required: true
schema:
type: boolean
style: form
- name: pagination_token
in: query
description: Pagination token to get next set of posts eligible for notes.
required: false
schema:
type: string
style: form
- name: max_results
in: query
description: Max results to return.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 10
style: form
- $ref: '#/components/parameters/NoteFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2NotesSearchNotesWrittenResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/notes/search/posts_eligible_for_notes:
get:
security:
- OAuth2UserToken:
- tweet.read
- UserToken: []
tags:
- Community Notes
summary: Search for Posts Eligible for Community Notes
description: Returns all the posts that are eligible for community notes.
externalDocs:
url: https://docs.x.com/x-api/community-notes/search-for-posts-eligible-for-community-notes
operationId: searchEligiblePosts
parameters:
- name: test_mode
in: query
description: If true, return a list of posts that are for the test. If false, return a list of posts that the bots can write proposed notes on the product.
required: true
schema:
type: boolean
style: form
- name: pagination_token
in: query
description: Pagination token to get next set of posts eligible for notes.
required: false
schema:
type: string
style: form
- name: max_results
in: query
description: Max results to return.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 10
style: form
- name: post_selection
in: query
description: 'The selection of posts to return. Valid values are ''feed_size: [small|large|xl|xxl], feed_lang: [en|es|...|all]''. Default (if not specified) is ''feed_size: small, feed_lang: en''. Only top AI writers have access to large, xl, and xxl size feeds.'
required: false
schema:
type: string
style: form
- $ref: '#/components/parameters/TweetFieldsParameter'
- $ref: '#/components/parameters/TweetExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2NotesSearchPostsEligibleForNotesResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/notes/{id}:
delete:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Community Notes
summary: Delete a Community Note
description: Deletes a community note.
externalDocs:
url: https://communitynotes.x.com/guide/api/overview
operationId: deleteCommunityNotes
parameters:
- name: id
in: path
description: The community note id to delete.
required: true
schema:
$ref: '#/components/schemas/NoteId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteNoteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
parameters:
TweetExpansionsParameter:
name: expansions
in: query
description: A comma separated list of fields to expand.
schema:
type: array
description: The list of fields you can expand for a [Tweet](#Tweet) object. If the field has an ID, it can be expanded into a full object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- article.cover_media
- article.media_entities
- attachments.media_keys
- attachments.media_source_tweet
- attachments.poll_ids
- author_id
- edit_history_tweet_ids
- entities.mentions.username
- geo.place_id
- in_reply_to_user_id
- entities.note.mentions.username
- referenced_tweets.id
- referenced_tweets.id.attachments.media_keys
- referenced_tweets.id.author_id
example:
- article.cover_media
- article.media_entities
- attachments.media_keys
- attachments.media_source_tweet
- attachments.poll_ids
- author_id
- edit_history_tweet_ids
- entities.mentions.username
- geo.place_id
- in_reply_to_user_id
- entities.note.mentions.username
- referenced_tweets.id
- referenced_tweets.id.attachments.media_keys
- referenced_tweets.id.author_id
explode: false
style: form
TweetFieldsParameter:
name: tweet.fields
in: query
description: A comma separated list of Tweet fields to display.
required: false
schema:
type: array
description: The fields available for a Tweet object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- article
- attachments
- author_id
- card_uri
- community_id
- context_annotations
- conversation_id
- created_at
- display_text_range
- edit_controls
- edit_history_tweet_ids
- entities
- geo
- id
- in_reply_to_user_id
- lang
- matched_media_notes
- media_metadata
- non_public_metrics
- note_request_suggestions
- note_tweet
- organic_metrics
- paid_partnership
- possibly_sensitive
- promoted_metrics
- public_metrics
- referenced_tweets
- reply_settings
- scopes
- source
- suggested_source_links
- suggested_source_links_with_counts
- text
- withheld
example:
- article
- attachments
- author_id
- card_uri
- community_id
- context_annotations
- conversation_id
- created_at
- display_text_range
- edit_controls
- edit_history_tweet_ids
- entities
- geo
- id
- in_reply_to_user_id
- lang
- matched_media_notes
- media_metadata
- non_public_metrics
- note_request_suggestions
- note_tweet
- organic_metrics
- paid_partnership
- possibly_sensitive
- promoted_metrics
- public_metrics
- referenced_tweets
- reply_settings
- scopes
- source
- suggested_source_links
- suggested_source_links_with_counts
- text
- withheld
explode: false
style: form
PollFieldsParameter:
name: poll.fields
in: query
description: A comma separated list of Poll fields to display.
required: false
schema:
type: array
description: The fields available for a Poll object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- duration_minutes
- end_datetime
- id
- options
- voting_status
example:
- duration_minutes
- end_datetime
- id
- options
- voting_status
explode: false
style: form
UserFieldsParameter:
name: user.fields
in: query
description: A comma separated list of User fields to display.
required: false
schema:
type: array
description: The fields available for a User object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- affiliation
- confirmed_email
- connection_status
- created_at
- description
- entities
- id
- is_identity_verified
- location
- most_recent_tweet_id
- name
- parody
- pinned_tweet_id
- profile_banner_url
- profile_image_url
- protected
- public_metrics
- receives_your_dm
- subscription
- subscription_type
- url
- username
- verified
- verified_followers_count
- verified_type
- withheld
example:
- affiliation
- confirmed_email
- connection_status
- created_at
- description
- entities
- id
- is_identity_verified
- location
- most_recent_tweet_id
- name
- parody
- pinned_tweet_id
- profile_banner_url
- profile_image_url
- protected
- public_metrics
- receives_your_dm
- subscription
- subscription_type
- url
- username
- verified
- verified_followers_count
- verified_type
- withheld
explode: false
style: form
NoteFieldsParameter:
name: note.fields
in: query
description: A comma separated list of Note fields to display.
required: false
schema:
type: array
description: The fields available for a Note object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- id
- info
- scoring_status
- status
- test_result
example:
- id
- info
- scoring_status
- status
- test_result
explode: false
style: form
PlaceFieldsParameter:
name: place.fields
in: query
description: A comma separated list of Place fields to display.
required: false
schema:
type: array
description: The fields available for a Place object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- contained_within
- country
- country_code
- full_name
- geo
- id
- name
- place_type
example:
- contained_within
- country
- country_code
- full_name
- geo
- id
- name
- place_type
explode: false
style: form
MediaFieldsParameter:
name: media.fields
in: query
description: A comma separated list of Media fields to display.
required: false
schema:
type: array
description: The fields available for a Media object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- alt_text
- duration_ms
- height
- media_key
- non_public_metrics
- organic_metrics
- preview_image_url
- promoted_metrics
- public_metrics
- type
- url
- variants
- width
example:
- alt_text
- duration_ms
- height
- media_key
- non_public_metrics
- organic_metrics
- preview_image_url
- promoted_metrics
- public_metrics
- type
- url
- variants
- width
explode: false
style: form
schemas:
HashtagEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/HashtagFields'
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
ContextAnnotationEntityFields:
type: object
description: Represents the data for the context annotation entity.
required:
- id
properties:
description:
type: string
description: Description of the context annotation entity.
id:
type: string
description: The unique id for a context annotation entity.
pattern: ^[0-9]{1,19}$
name:
type: string
description: Name of the context annotation entity.
EvaluateNoteRequest:
type: object
required:
- post_id
- note_text
properties:
note_text:
type: string
description: Text for the community note.
post_id:
$ref: '#/components/schemas/TweetId'
additionalProperties: false
Media:
type: object
required:
- type
properties:
height:
$ref: '#/components/schemas/MediaHeight'
media_key:
$ref: '#/components/schemas/MediaKey'
type:
type: string
width:
$ref: '#/components/schemas/MediaWidth'
discriminator:
propertyName: type
mapping:
animated_gif: '#/components/schemas/AnimatedGif'
photo: '#/components/schemas/Photo'
video: '#/components/schemas/Video'
User:
type: object
description: The X User object.
required:
- id
- name
- username
properties:
affiliation:
type: object
description: Metadata about a user's affiliation.
properties:
badge_url:
type: string
description: The badge URL corresponding to the affiliation.
format: uri
description:
type: string
description: The description of the affiliation.
url:
type: string
description: The URL, if available, to details about an affiliation.
format: uri
user_id:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UserId'
connection_status:
type: array
description: Returns detailed information about the relationship between two users.
minItems: 0
items:
type: string
description: Type of connection between users.
enum:
- follow_request_received
- follow_request_sent
- blocking
- followed_by
- following
- muting
created_at:
type: string
description: Creation time of this User.
format: date-time
description:
type: string
description: The text of this User's profile description (also known as bio), if the User provided one.
entities:
type: object
description: A list of metadata found in the User's profile description.
properties:
description:
$ref: '#/components/schemas/FullTextEntities'
url:
type: object
description: Expanded details for the URL specified in the User's profile, with start and end indices.
properties:
urls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlEntity'
id:
$ref: '#/components/schemas/UserId'
location:
type: string
description: The location specified in the User's profile, if the User provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.
most_recent_tweet_id:
$ref: '#/components/schemas/TweetId'
name:
type: string
description: The friendly name of this User, as shown on their profile.
pinned_tweet_id:
$ref: '#/components/schemas/TweetId'
profile_banner_url:
type: string
description: The URL to the profile banner for this User.
format: uri
profile_image_url:
type: string
description: The URL to the profile image for this User.
format: uri
protected:
type: boolean
description: Indicates if this User has chosen to protect their Posts (in other words, if this User's Posts are private).
public_metrics:
type: object
description: A list of metrics for this User.
required:
- followers_count
- following_count
- tweet_count
- listed_count
properties:
followers_count:
type: integer
description: Number of Users who are following this User.
following_count:
type: integer
description: Number of Users this User is following.
like_count:
type: integer
description: The number of likes created by this User.
listed_count:
type: integer
description: The number of lists that include this User.
tweet_count:
type: integer
description: The number of Posts (including Retweets) posted by this User.
receives_your_dm:
type: boolean
description: Indicates if you can send a DM to this User
subscription_type:
type: string
description: 'The X Blue subscription type of the user, eg: Basic, Premium, PremiumPlus or None.'
enum:
- Basic
- Premium
- PremiumPlus
- None
url:
type: string
description: The URL specified in the User's profile.
username:
$ref: '#/components/schemas/UserName'
verified:
type: boolean
description: Indicate if this User is a verified X User.
verified_type:
type: string
description: 'The X Blue verified type of the user, eg: blue, government, business or none.'
enum:
- blue
- government
- business
- none
withheld:
$ref: '#/components/schemas/UserWithheld'
example:
created_at: '2013-12-14T04:35:55Z'
id: '2244994945'
name: X Dev
protected: false
username: TwitterDev
UserName:
type: string
description: The X handle (screen name) of this user.
pattern: ^[A-Za-z0-9_]{1,15}$
NoteRatingCountsPerModel:
type: object
description: The rating counts of a Community Note per model.
properties:
negative_factor_bucket_counts:
$ref: '#/components/schemas/NoteFactorBucketCounts'
neutral_factor_bucket_counts:
$ref: '#/components/schemas/NoteFactorBucketCounts'
positive_factor_bucket_counts:
$ref: '#/components/schemas/NoteFactorBucketCounts'
MentionEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/MentionFields'
NoteInfo:
type: object
description: A X Community Note is a note on a Post.
required:
- text
- classification
- misleading_tags
- trustworthy_sources
properties:
classification:
$ref: '#/components/schemas/NoteClassification'
is_media_note:
type: boolean
description: Whether the note is a media note.
misleading_tags:
type: array
items:
$ref: '#/components/schemas/MisleadingTags'
text:
type: string
description: The text summary in the Community Note.
pattern: ^(?=[\s\S]*https?://\S+)[\s\S]+$
trustworthy_sources:
type: boolean
description: Whether the note provided trustworthy links.
additionalProperties: false
ContextAnnotation:
type: object
description: Annotation inferred from the Tweet text.
required:
- domain
- entity
properties:
domain:
$ref: '#/components/schemas/ContextAnnotationDomainFields'
entity:
$ref: '#/components/schemas/ContextAnnotationEntityFields'
UserId:
type: string
description: Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
pattern: ^[0-9]{1,19}$
example: '2244994945'
Expansions:
type: object
properties:
media:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Media'
places:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Place'
polls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Poll'
topics:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Topic'
tweets:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Tweet'
users:
type: array
minItems: 1
items:
$ref: '#/components/schemas/User'
PollOption:
type: object
description: Describes a choice in a Poll object.
required:
- position
- label
- votes
properties:
label:
$ref: '#/components/schemas/PollOptionLabel'
position:
type: integer
description: Position of this choice in the poll.
votes:
type: integer
description: Number of users who voted for this choice.
CommunityId:
type: string
description: The unique identifier of this Community.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
EntityIndicesInclusiveInclusive:
type: object
description: Represent a boundary range (start and end index) for a recognized entity (for example a hashtag or a mention). `start` must be smaller than `end`. The start index is inclusive, the end index is inclusive.
required:
- start
- end
properties:
end:
type: integer
description: Index (zero-based) at which position this entity ends. The index is inclusive.
minimum: 0
example: 61
start:
type: integer
description: Index (zero-based) at which position this entity starts. The index is inclusive.
minimum: 0
example: 50
NoteScoringStatus:
type: object
description: The scoring status of a Community Note.
properties:
has_access:
type: boolean
description: Whether the user has access to the scoring status of the Community Note.
rating_counts_per_model:
type: object
description: Rating count stats per model.
properties:
model_name:
type: string
description: The name of the model.
value:
$ref: '#/components/schemas/NoteRatingCountsPerModel'
NoteId:
type: string
description: The unique identifier of this Community Note.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
ReplySettingsWithVerifiedUsers:
type: string
description: Shows who can reply a Tweet. Fields returned are everyone, mentioned_users, subscribers, verified and following.
pattern: ^[A-Za-z]{1,12}$
enum:
- everyone
- mentionedUsers
- following
- other
- subscribers
- verified
CashtagFields:
type: object
description: Represent the portion of text recognized as a Cashtag, and its start and end position within the text.
required:
- tag
properties:
tag:
type: string
example: TWTR
PlaceType:
type: string
enum:
- poi
- neighborhood
- city
- admin
- country
- unknown
example: city
Geo:
type: object
required:
- type
- bbox
- properties
properties:
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
minimum: -180
maximum: 180
format: double
example:
- -105.193475
- 39.60973
- -105.053164
- 39.761974
geometry:
$ref: '#/components/schemas/Point'
properties:
type: object
type:
type: string
enum:
- Feature
NoteFactorBucketCounts:
type: object
description: Rating counts for a rater factor bucket.
properties:
helpful_count:
type: integer
description: The count of helpful ratings.
helpful_tag_counts:
type: object
description: Helpful tag counts.
properties:
tag_count:
type: integer
description: The count of the tag.
tag_name:
type: string
description: The name of the tag.
not_helpful_count:
type: integer
description: The count of not helpful ratings.
not_helpful_tag_counts:
type: object
description: Not helpful tag counts.
properties:
tag_count:
type: integer
description: The count of the tag.
tag_name:
type: string
description: The name of the tag.
somewhat_helpful_count:
type: integer
description: The count of somewhat helpful ratings.
Problem:
type: object
description: An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
required:
- type
- title
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
discriminator:
propertyName: type
mapping:
about:blank: '#/components/schemas/GenericProblem'
https://api.twitter.com/2/problems/client-disconnected: '#/components/schemas/ClientDisconnectedProblem'
https://api.twitter.com/2/problems/client-forbidden: '#/components/schemas/ClientForbiddenProblem'
https://api.twitter.com/2/problems/conflict: '#/components/schemas/ConflictProblem'
https://api.twitter.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
https://api.twitter.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
https://api.twitter.com/2/problems/noncompliant-rules: '#/components/schemas/NonCompliantRulesProblem'
https://api.twitter.com/2/problems/not-authorized-for-field: '#/components/schemas/FieldUnauthorizedProblem'
https://api.twitter.com/2/problems/not-authorized-for-resource: '#/components/schemas/ResourceUnauthorizedProblem'
https://api.twitter.com/2/problems/operational-disconnect: '#/components/schemas/OperationalDisconnectProblem'
https://api.twitter.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
https://api.twitter.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
https://api.twitter.com/2/problems/rule-cap: '#/components/schemas/RulesCapProblem'
https://api.twitter.com/2/problems/streaming-connection: '#/components/schemas/ConnectionExceptionProblem'
https://ap
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter-x/refs/heads/main/openapi/twitter-x-community-notes-api-openapi.yml