Twitter/X Community Notes API
The Community Notes API from Twitter/X — 5 operation(s) for community notes.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/twitter-x-community-notes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.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:
schemas:
MisleadingTags:
type: string
description: Community Note misleading tags type.
enum:
- disputed_claim_as_fact
- factual_error
- manipulated_media
- misinterpreted_satire
- missing_important_context
- other
- outdated_information
Topic:
type: object
description: The topic of a Space, as selected by its creator.
required:
- id
- name
properties:
description:
type: string
description: The description of the given topic.
example: All about technology
id:
$ref: '#/components/schemas/TopicId'
name:
type: string
description: The name of the given topic.
example: Technology
Url:
type: string
description: A validly formatted URL.
format: uri
example: https://developer.twitter.com/en/docs/twitter-api
Place:
type: object
required:
- id
- full_name
properties:
contained_within:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PlaceId'
country:
type: string
description: The full name of the county in which this place exists.
example: United States
country_code:
$ref: '#/components/schemas/CountryCode'
full_name:
type: string
description: The full name of this place.
example: Lakewood, CO
geo:
$ref: '#/components/schemas/Geo'
id:
$ref: '#/components/schemas/PlaceId'
name:
type: string
description: The human readable name of this place.
example: Lakewood
place_type:
$ref: '#/components/schemas/PlaceType'
MediaKey:
type: string
description: The Media Key identifier for this attachment.
pattern: ^([0-9]+)_([0-9]+)$
NoteId:
type: string
description: The unique identifier of this Community Note.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
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'
Note:
type: object
description: A X Community Note is a note on a Post.
required:
- id
- post_id
- note_info
properties:
id:
$ref: '#/components/schemas/NoteId'
info:
$ref: '#/components/schemas/NoteInfo'
post_id:
$ref: '#/components/schemas/TweetId'
scoring_status:
$ref: '#/components/schemas/NoteScoringStatus'
status:
$ref: '#/components/schemas/NoteRatingStatus'
test_result:
$ref: '#/components/schemas/NoteTestResult'
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
Tweet:
type: object
properties:
attachments:
type: object
description: Specifies the type of attachments (if any) present in this Tweet.
properties:
media_keys:
type: array
description: A list of Media Keys for each one of the media attachments (if media are attached).
minItems: 1
items:
$ref: '#/components/schemas/MediaKey'
media_source_tweet_id:
type: array
description: A list of Posts the media on this Tweet was originally posted in. For example, if the media on a tweet is re-used in another Tweet, this refers to the original, source Tweet..
minItems: 1
items:
$ref: '#/components/schemas/TweetId'
poll_ids:
type: array
description: A list of poll IDs (if polls are attached).
minItems: 1
items:
$ref: '#/components/schemas/PollId'
author_id:
$ref: '#/components/schemas/UserId'
community_id:
$ref: '#/components/schemas/CommunityId'
context_annotations:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ContextAnnotation'
conversation_id:
$ref: '#/components/schemas/TweetId'
created_at:
type: string
description: Creation time of the Tweet.
format: date-time
example: '2021-01-06T18:40:40.000Z'
display_text_range:
$ref: '#/components/schemas/DisplayTextRange'
edit_controls:
type: object
required:
- is_edit_eligible
- editable_until
- edits_remaining
properties:
editable_until:
type: string
description: Time when Tweet is no longer editable.
format: date-time
example: '2021-01-06T18:40:40.000Z'
edits_remaining:
type: integer
description: Number of times this Tweet can be edited.
is_edit_eligible:
type: boolean
description: Indicates if this Tweet is eligible to be edited.
example: false
edit_history_tweet_ids:
type: array
description: A list of Tweet Ids in this Tweet chain.
minItems: 1
items:
$ref: '#/components/schemas/TweetId'
entities:
$ref: '#/components/schemas/FullTextEntities'
geo:
type: object
description: The location tagged on the Tweet, if the user provided one.
properties:
coordinates:
$ref: '#/components/schemas/Point'
place_id:
$ref: '#/components/schemas/PlaceId'
id:
$ref: '#/components/schemas/TweetId'
in_reply_to_user_id:
$ref: '#/components/schemas/UserId'
lang:
type: string
description: Language of the Tweet, if detected by X. Returned as a BCP47 language tag.
example: en
matched_media_notes:
type: object
description: The matched media notes for the post.
properties:
match_status:
type: string
description: The status of the media note match.
example: matched_and_shown
note_id:
$ref: '#/components/schemas/NoteId'
non_public_metrics:
type: object
description: Nonpublic engagement metrics for the Tweet at the time of the request.
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
note_request_suggestions:
type: object
description: The note request suggestions for the post.
properties:
source_link:
$ref: '#/components/schemas/UrlEntity'
suggestion:
type: string
description: The text of the note request suggestion.
suggestion_id:
type: string
description: The unique identifier of the note request suggestion.
note_tweet:
type: object
description: The full-content of the Tweet, including text beyond 280 characters.
properties:
entities:
type: object
properties:
cashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/CashtagEntity'
hashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/HashtagEntity'
mentions:
type: array
minItems: 1
items:
$ref: '#/components/schemas/MentionEntity'
urls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlEntity'
text:
$ref: '#/components/schemas/NoteTweetText'
organic_metrics:
type: object
description: Organic nonpublic engagement metrics for the Tweet at the time of the request.
required:
- impression_count
- retweet_count
- reply_count
- like_count
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
like_count:
type: integer
description: Number of times this Tweet has been liked.
reply_count:
type: integer
description: Number of times this Tweet has been replied to.
retweet_count:
type: integer
description: Number of times this Tweet has been Retweeted.
paid_partnership:
type: boolean
description: Indicates if this Post is a paid partnership, i.e. it has been disclosed by the author as containing paid promotion.
example: false
possibly_sensitive:
type: boolean
description: Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.
example: false
promoted_metrics:
type: object
description: Promoted nonpublic engagement metrics for the Tweet at the time of the request.
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
like_count:
type: integer
description: Number of times this Tweet has been liked.
format: int32
reply_count:
type: integer
description: Number of times this Tweet has been replied to.
format: int32
retweet_count:
type: integer
description: Number of times this Tweet has been Retweeted.
format: int32
public_metrics:
type: object
description: Engagement metrics for the Tweet at the time of the request.
required:
- retweet_count
- reply_count
- like_count
- impression_count
- bookmark_count
properties:
bookmark_count:
type: integer
description: Number of times this Tweet has been bookmarked.
format: int32
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
like_count:
type: integer
description: Number of times this Tweet has been liked.
quote_count:
type: integer
description: Number of times this Tweet has been quoted.
reply_count:
type: integer
description: Number of times this Tweet has been replied to.
retweet_count:
type: integer
description: Number of times this Tweet has been Retweeted.
referenced_tweets:
type: array
description: A list of Posts this Tweet refers to. For example, if the parent Tweet is a Retweet, a Quoted Tweet or a Reply, it will include the related Tweet referenced to by its parent.
minItems: 1
items:
type: object
required:
- type
- id
properties:
id:
$ref: '#/components/schemas/TweetId'
type:
type: string
enum:
- retweeted
- quoted
- replied_to
reply_settings:
$ref: '#/components/schemas/ReplySettingsWithVerifiedUsers'
scopes:
type: object
description: The scopes for this tweet
properties:
followers:
type: boolean
description: Indicates if this Tweet is viewable by followers without the Tweet ID
example: false
source:
type: string
description: This is deprecated.
suggested_source_links:
type: array
minItems: 0
items:
$ref: '#/components/schemas/UrlEntity'
suggested_source_links_with_counts:
type: object
description: Suggested source links and the number of requests that included each link.
properties:
count:
type: integer
description: Number of note requests that included the source link.
url:
$ref: '#/components/schemas/UrlEntity'
text:
$ref: '#/components/schemas/TweetText'
username:
$ref: '#/components/schemas/UserName'
withheld:
$ref: '#/components/schemas/TweetWithheld'
example:
author_id: '2244994945'
created_at: Wed Jan 06 18:40:40 +0000 2021
id: '1346889436626259968'
text: Learn how to use the user Tweet timeline and user mention timeline endpoints in the X API v2 to explore Tweet\u2026 https:\/\/t.co\/56a0vZUx7i
username: XDevelopers
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.
PollId:
type: string
description: Unique identifier of this poll.
pattern: ^[0-9]{1,19}$
example: '1365059861688410112'
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
ResultCount:
type: integer
description: The number of results returned in this response.
format: int32
CreateNoteRequest:
type: object
title: Note
required:
- test_mode
- post_id
- info
properties:
info:
$ref: '#/components/schemas/NoteInfo'
post_id:
$ref: '#/components/schemas/TweetId'
test_mode:
type: boolean
description: If true, the note being submitted is only for testing the capability of the bot, and won't be publicly visible. If false, the note being submitted will be a new proposed note on the product.
additionalProperties: false
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
DeleteNoteResponse:
type: object
properties:
data:
type: object
required:
- deleted
properties:
deleted:
type: boolean
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
NoteRatingStatus:
type: string
description: Community Note rating status
enum:
- currently_rated_helpful
- currently_rated_not_helpful
- firm_reject
- insufficient_consensus
- minimum_ratings_not_met
- needs_more_ratings
- needs_your_help
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'
ContextAnnotationDomainFields:
type: object
description: Represents the data for the context annotation domain.
required:
- id
properties:
description:
type: string
description: Description of the context annotation domain.
id:
type: string
description: The unique id for a context annotation domain.
pattern: ^[0-9]{1,19}$
name:
type: string
description: Name of the context annotation domain.
MediaWidth:
type: integer
description: The width of the media in pixels.
minimum: 0
CommunityId:
type: string
description: The unique identifier of this Community.
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
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
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.
TweetWithheld:
type: object
description: Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country).
required:
- copyright
- country_codes
properties:
copyright:
type: boolean
description: Indicates if the content is being withheld for on the basis of copyright infringement.
country_codes:
type: array
description: Provides a list of countries where this content is not available.
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/CountryCode'
scope:
type: string
description: Indicates whether the content being withheld is the `tweet` or a `user`.
enum:
- tweet
- user
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://api.twitter.com/2/problems/unsupported-authentication: '#/components/schemas/UnsupportedAuthenticationProblem'
https://api.twitter.com/2/problems/usage-capped: '#/components/schemas/UsageCapExceededProblem'
UrlImage:
type: object
description: Represent the information for the URL image.
properties:
height:
$ref: '#/components/schemas/MediaHeight'
url:
$ref: '#/components/schemas/Url'
width:
$ref: '#/components/schemas/MediaWidth'
PollOptionLabel:
type: string
description: The text of a poll choice.
minLength: 1
maxLength: 25
EntityIndicesInclusiveExclusive:
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 exclusive.
required:
- start
- end
properties:
end:
type: integer
description: Index (zero-based) at which position this entity ends. The index is exclusive.
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
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:
ty
# --- 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