X Community Notes API
Endpoints related to retrieving, searching, and modifying Community Notes — 5 operation(s) in the X-published contract.
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/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 core endpoints
version: '2.168'
title: X API v2 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
description: Endpoints related to retrieving, searching, and modifying Community Notes
externalDocs:
description: Find out more
url: https://docs.x.com/x-api/community-notes/introduction
paths:
/2/notes:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Community Notes
summary: Create Community Notes
operationId: createCommunityNotes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommunityNotesRequest'
required: true
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommunityNotesResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/notes/evaluate:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Community Notes
summary: Evaluate Community Notes
operationId: evaluateCommunityNotes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluateCommunityNotesRequest'
required: true
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluateCommunityNotesResponse'
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 Community Notes Written
operationId: searchCommunityNotesWritten
parameters:
- name: test_mode
in: query
required: true
schema:
type: boolean
style: form
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 10
style: form
- name: pagination_token
in: query
required: false
schema:
type: string
style: form
- $ref: '#/components/parameters/NoteFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCommunityNotesWrittenResponse'
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 Eligible Posts
operationId: searchEligiblePosts
parameters:
- name: test_mode
in: query
required: true
schema:
type: boolean
style: form
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 10
style: form
- name: pagination_token
in: query
required: false
schema:
type: string
style: form
- name: post_selection
in: query
required: false
schema:
type: string
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchEligiblePostsResponse'
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
required: true
schema:
$ref: '#/components/schemas/NoteId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCommunityNotesResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
CreateCommunityNotesResponse:
type: object
properties:
data:
$ref: '#/components/schemas/CreateCommunityNotesResponseData'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
PostPublicMetrics:
type: object
description: Engagement metrics for the Post at the time of the request.
required:
- repost_count
- reply_count
- like_count
- quote_count
- bookmark_count
- impression_count
properties:
bookmark_count:
type: integer
description: Number of times this Post has been bookmarked.
format: int64
impression_count:
type: integer
description: Number of times this Post has been viewed.
format: int64
like_count:
type: integer
description: Number of likes on this Post.
format: int64
quote_count:
type: integer
description: Number of quote Posts of this Post.
format: int64
reply_count:
type: integer
description: Number of replies to this Post.
format: int64
repost_count:
type: integer
description: Number of times this Post has been reposted.
format: int64
PostDisplayTextRange:
type: array
description: The inclusive start and exclusive end indices of the displayable content of the Post.
minItems: 2
maxItems: 2
items:
type: integer
format: int64
Expansions:
type: object
properties:
media:
type: array
items:
$ref: '#/components/schemas/Media'
places:
type: array
items:
$ref: '#/components/schemas/Place'
polls:
type: array
items:
$ref: '#/components/schemas/Poll'
posts:
type: array
items:
$ref: '#/components/schemas/Post'
topics:
type: array
items:
$ref: '#/components/schemas/Topic'
users:
type: array
items:
$ref: '#/components/schemas/User'
Media:
type: object
properties:
alt_text:
type: string
duration_ms:
type: integer
height:
type: integer
media_key:
type: string
non_public_metrics:
$ref: '#/components/schemas/MediaNonPublicMetrics'
organic_metrics:
$ref: '#/components/schemas/MediaOrganicMetrics'
preview_image_url:
type: string
promoted_metrics:
$ref: '#/components/schemas/MediaPromotedMetrics'
public_metrics:
$ref: '#/components/schemas/MediaPublicMetrics'
type:
type: string
url:
type: string
variants:
$ref: '#/components/schemas/MediaVariants'
width:
type: integer
Note:
type: object
properties:
id:
type: string
info:
$ref: '#/components/schemas/NoteInfo'
scoring_status:
$ref: '#/components/schemas/NoteScoringStatus'
status:
type: string
test_result:
$ref: '#/components/schemas/NoteTestResult'
PostGeo:
type: object
description: The location tagged on the Post, if the user provided one.
properties:
coordinates:
type:
- object
- 'null'
description: A GeoJSON Point geometry.
required:
- type
- coordinates
properties:
coordinates:
type: array
description: '[longitude, latitude].'
minItems: 2
maxItems: 2
items:
type: number
format: double
type:
type: string
description: The GeoJSON geometry type.
enum:
- Point
place_id:
type:
- string
- 'null'
description: The unique identifier of the tagged place.
FieldHydrationFailureProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/field-hydration-failure
NoteInfo:
type: object
description: Details about the Community Note's content, classification and source.
properties:
classification:
type:
- string
- 'null'
description: How the noted Post was classified (snake_case).
misleading_tags:
type:
- array
- 'null'
description: Reasons the noted Post may be misleading (snake_case).
items:
type: string
post_id:
type:
- string
- 'null'
description: Unique identifier of the Post this note is about.
rating_status:
type:
- string
- 'null'
description: Current rating status of the note.
text:
type:
- string
- 'null'
description: The text of the Community Note.
trustworthy_sources:
type:
- boolean
- 'null'
description: Whether the note cites trustworthy sources.
PostSuggestedSourceLinks:
type: array
description: URLs suggested as sources for this Post.
items:
type: string
NotAuthorizedForResourceProblem:
type: object
required:
- type
- title
- detail
- resource_type
properties:
detail:
type: string
parameter:
type: string
resource_id:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/not-authorized-for-resource
value:
type: string
PostEntities:
type: object
description: A list of metadata entities (hashtags, mentions, URLs) found in the Post text.
properties:
cashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
hashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
mentions:
type:
- array
- 'null'
items:
type: object
description: A user mention entity.
required:
- start
- end
properties:
end:
type: integer
format: int64
id:
type:
- string
- 'null'
start:
type: integer
format: int64
username:
type:
- string
- 'null'
urls:
type:
- array
- 'null'
items:
type: object
description: A URL entity found in the Post text, enriched with link metadata.
required:
- start
- end
properties:
description:
type:
- string
- 'null'
description: Description of the linked page, when available.
display_url:
type:
- string
- 'null'
description: The URL as displayed in the Post text.
end:
type: integer
format: int64
expanded_url:
type:
- string
- 'null'
description: The fully resolved URL.
images:
type:
- array
- 'null'
items:
type: object
description: A preview image for a linked page.
properties:
height:
type:
- integer
- 'null'
format: int64
url:
type:
- string
- 'null'
width:
type:
- integer
- 'null'
format: int64
media_key:
type:
- string
- 'null'
start:
type: integer
format: int64
status:
type:
- integer
- 'null'
description: HTTP status from resolving the URL.
format: int64
title:
type:
- string
- 'null'
description: Title of the linked page, when available.
unwound_url:
type:
- string
- 'null'
description: The final destination after following redirects.
url:
type:
- string
- 'null'
description: The t.co shortened URL.
MediaVariants:
type: array
description: Each media object may have multiple display or playback variants, with different resolutions or formats.
items:
type: object
description: A single playback or display variant of a media object.
properties:
bit_rate:
type:
- integer
- 'null'
description: The bit rate of this variant, in bits per second. Absent for playlist variants.
format: int64
content_type:
type:
- string
- 'null'
description: The MIME type of this variant, for example "video/mp4" or "application/x-mpegURL".
url:
type:
- string
- 'null'
description: The URL to this media variant.
DeleteCommunityNotesResponse:
type: object
properties:
data:
$ref: '#/components/schemas/DeleteCommunityNotesResponseData'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
PostReferencedPosts:
type: array
description: A list of Posts this Post refers to. If the Post is a Retweet, Quote or Reply, it includes the referenced Post's type and ID.
items:
type: object
description: A reference from this Post to another Post (repost, quote, or reply).
required:
- type
- id
properties:
id:
type: string
description: Unique identifier of the referenced Post.
type:
description: How this Post references the other Post.
oneOf:
- type: string
description: The kind of Post-to-Post reference.
enum:
- retweeted
- quoted
- replied_to
EvaluateCommunityNotesRequest:
type: object
required:
- post_id
- note_text
properties:
note_text:
type: string
description: Text of the community note to evaluate.
post_id:
type: string
description: ID of the Post the note evaluates.
pattern: ^[0-9]{1,19}$
additionalProperties: false
SearchEligiblePostsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Post'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
meta:
type: object
properties:
next_token:
type: string
description: Pagination token for the next page of results.
result_count:
type: integer
description: Number of items in the data array.
format: int32
MediaNonPublicMetrics:
type: object
description: Nonpublic engagement metrics for the media at the time of the request.
properties:
playback_0_count:
type:
- integer
- 'null'
description: Number of users who started playback (0% quartile) of this video.
format: int64
playback_100_count:
type:
- integer
- 'null'
description: Number of users who completed playback (100% quartile) of this video.
format: int64
playback_25_count:
type:
- integer
- 'null'
description: Number of users who watched at least 25% of this video.
format: int64
playback_50_count:
type:
- integer
- 'null'
description: Number of users who watched at least 50% of this video.
format: int64
playback_75_count:
type:
- integer
- 'null'
description: Number of users who watched at least 75% of this video.
format: int64
UserConnectionStatus:
type: array
description: Returns detailed information about the relationship between two users.
items:
type: string
description: A connection between the authenticated User and this User.
enum:
- blocking
- follow_request_received
- follow_request_sent
- followed_by
- following
- muting
SearchCommunityNotesWrittenResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Note'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
meta:
type: object
properties:
next_token:
type: string
description: Pagination token for the next page of results.
result_count:
type: integer
description: Number of items in the data array.
format: int32
NotAuthorizedForFieldProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
parameter:
type: string
resource_id:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/not-authorized-for-field
value:
type: string
CreateCommunityNotesResponseData:
type: object
required:
- id
properties:
id:
type: string
description: Unique identifier of the created Community Note.
NoteTestResult:
type: object
description: AI evaluation results for the Community Note (returned in test mode).
properties:
evaluation_outcome:
type:
- array
- 'null'
description: Per-evaluator outcomes for the note.
items:
type: object
description: A single evaluator's outcome for a Community Note.
required:
- evaluator_type
- evaluator_score_bucket
properties:
evaluator_score_bucket:
type: string
description: The score bucket the evaluator assigned.
evaluator_type:
type: string
description: The type of evaluator that produced this outcome.
Post:
type: object
properties:
article:
type: object
article_title:
type: object
description: Metadata about the long-form Article attached to this Post, if any.
attachments:
$ref: '#/components/schemas/PostAttachments'
author_id:
type: string
description: Unique identifier of the author of this Post.
card_uri:
type: string
community_id:
type: string
description: The unique identifier of the Community this Post belongs to, if any.
context_annotations:
$ref: '#/components/schemas/PostContextAnnotations'
conversation_id:
type: string
description: The ID of the conversation this Post belongs to (matches the root Post's ID).
created_at:
type: string
description: Creation time of the Post.
format: date-time
display_text_range:
$ref: '#/components/schemas/PostDisplayTextRange'
edit_controls:
$ref: '#/components/schemas/PostEditControls'
edit_history_post_ids:
type: array
description: A list of Post IDs in this Post's edit history chain.
items:
type: string
entities:
$ref: '#/components/schemas/PostEntities'
geo:
$ref: '#/components/schemas/PostGeo'
id:
type: string
description: Unique identifier of this Post.
in_reply_to_user_id:
type: string
description: Unique identifier of the User this Post is replying to.
lang:
type: string
description: Language of the Post, if detected by X. Returned as a BCP47 language tag.
matched_media_notes:
$ref: '#/components/schemas/PostMatchedMediaNotes'
media_metadata:
$ref: '#/components/schemas/PostMediaMetadata'
non_public_metrics:
type: object
description: Nonpublic engagement metrics for the Post at the time of the request.
note_post:
$ref: '#/components/schemas/PostNotePost'
note_request_suggestions:
$ref: '#/components/schemas/PostNoteRequestSuggestions'
organic_metrics:
type: object
description: Organic nonpublic engagement metrics for the Post at the time of the request.
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.
possibly_sensitive:
type: boolean
description: Indicates if this Post contains URLs marked as sensitive, for example content suitable for mature audiences.
promoted_metrics:
type: object
description: Promoted nonpublic engagement metrics for the Post at the time of the request.
public_metrics:
$ref: '#/components/schemas/PostPublicMetrics'
referenced_posts:
$ref: '#/components/schemas/PostReferencedPosts'
reply_settings:
type: string
description: Shows who can reply to this Post.
scopes:
$ref: '#/components/schemas/PostScopes'
source:
type: string
description: The name of the app the user posted from. This is deprecated.
suggested_source_links:
$ref: '#/components/schemas/PostSuggestedSourceLinks'
suggested_source_links_with_counts:
$ref: '#/components/schemas/PostSuggestedSourceLinksWithCounts'
text:
type: string
description: The content of the Post.
username:
type: string
withheld:
$ref: '#/components/schemas/PostWithheld'
PostNoteRequestSuggestions:
type: array
description: Community-Notes request suggestions for this Post.
items:
type: object
description: A Community-Notes request suggestion for this Post.
properties:
source_link:
type:
- string
- 'null'
description: A suggested source link supporting the note request.
suggestion:
type:
- string
- 'null'
description: The text of the note request suggestion.
suggestion_id:
type:
- string
- 'null'
description: The unique identifier of the note request suggestion.
PostNotePost:
type: object
description: The full content of the Post, including text beyond 280 characters.
required:
- text
properties:
entities:
type:
- object
- 'null'
description: Metadata entities (hashtags, cashtags, mentions, URLs) found in the note Post text.
properties:
cashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
hashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
mentions:
type:
- array
- 'null'
items:
type: object
description: A user mention entity.
required:
- start
- end
properties:
end:
type: integer
format: int64
id:
type:
- string
- 'null'
start:
type: integer
format: int64
username:
type:
- string
- 'null'
urls:
type:
- array
- 'null'
items:
type: object
description: A URL entity found in note Post text.
required:
- start
- end
properties:
display_url:
type:
- string
- 'null'
end:
type: integer
format: int64
expanded_url:
type:
- string
- 'null'
start:
type: integer
format: int64
url:
type:
- string
- 'null'
text:
type: string
description: The full note text of the Post.
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
InvalidRequestProblem:
type: object
required:
- type
- title
- detail
properties:
detail:
type: string
parameter:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/invalid-request
value:
type: string
EvaluateCommun
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/x/refs/heads/main/openapi/x-community-notes-api-openapi.yml