XTools/API
Interactive OpenAPI docs are at xtools.wmcloud.org/api. These on-wiki docs are meant to supplement it. |
The XTools features a rich API for much of the data available through the web interface. Out of courtesy we ask you make requests synchronously – as in one full round trip – before making a new request. Please leave an informative user agent in your request so we can contact you if we need to.
Errors and warnings
Error messages are in the format specified by RFC 7807, with at minimum status
, title
and details
properties.
Please log any responses with a warning
property as this will announce deprecations and future changes.
To ensure performance and stability, most endpoints related to users will return a 501 response code if the user has made an exceptionally high number of edits. In the future, requests for such users may be permitted but will require authentication.
Endpoints
Change log
3.21.0 (upcoming)
Page API
/api/page/pageinfo
endpoint- The
last_edit_id
property will be removed. Use themodified_rev_id
property instead. - The
author
andauthor_editcount
properties will be removed. Use thecreator
andcreator_editcount
properties instead. - The
ip_edits
property will be removed. Use theanon_edits
property instead.
- The
3.20.0 (2024-08-15)
Common to all APIs
- All
timestamp
properties are now returned as ISO 8601 in the form of YYYY-MM-DDTHH:MM:SSZ. page_title
andfull_page_title
always return values with underscores replaced with spaces.minor
andreverted
properties are always boolean instead of 0 or 1.
Page API
- The
/api/page/articleinfo
endpoint has been renamed to/api/page/pageinfo
.- The
watchers
property returnsnull
instead of zero if the number of watchers is unknown. - The
author
andauthor_editcount
properties have been renamed tocreator
andcreator_editcount
, respectively. - The
last_edit_id
property has been renamed tomodified_rev_id
. - The
created_at
andmodified_at
properties are returned as ISO 8601 in the form of YYYY-MM-DDTHH:MM:SSZ.
- The
User API
- The
/api/user/category_editcount
endpoint propertycategories
is always returned as an array, even if there's only one element. - The
/api/user/month_counts
endpoint gives thetotals
as an array keyed by namespace and then year/month in the format YYYY-MM, with the count as the values.
3.18.0 (2023-07-10)
Version 3.18.0 introduced the first OpenAPI Specification of the XTools API. For the sake of consistency, many of the endpoints now have new standardized responses, and a few endpoints have been renamed or removed. XTools 3.18.0 was released on July 10, 2023.
Here is a summary of the breaking changes:
Common to all APIs
- All
page_namespace
properties are now namednamespace
. - All
page_is_redirect
properties are now namedredirect
, and this returns a boolean, not an integer. - All
rev_timestamp
properties are now namedtimestamp
.
Project API
- The
/api/users_groups
and/api/admins_groups
endpoints have been removed. Use/api/admin_groups
,/api/patroller_groups
and/api/steward_groups
instead. - The
/api/project/automated_tools
endpoint results are now nested under thetools
property.
Page API
- The
/api/articleinfo
endpoint is removed. Use/api/page/articleinfo
instead. - The
/api/page/assessments
endpoint results are now nested under thepages
property.
User API
- The
/api/user/automated_tools
endpoint has been removed. Use/api/project/automated_tools
instead. - The
/api/user/pages_count
endpoint now always groups results by namespace, even if a specific namespace was provided. Before, it only grouped by namespace ifall
was provided as the value for thenamespace
parameter. - The
/api/user/pages
endpoint- Now always groups results by namespace, even if a specific namespace was provided. Before, it only grouped by namespace if
all
was provided as the value for thenamespace
parameter. - Each page has the properties
deleted
(whether the page is deleted or not),namespace
,page_title
,full_page_title
,redirect
(boolean),timestamp
,rev_id
,rev_length
,length
(current length of the page),recreated
, andassessment
(with keysclass
,badge
,color
andcategory
). pa_importance
property is no longer included, as this represents the importance level of only a single WikiProjects and not the page overall.human_time
andraw_time
properties are removed. Usetimestamp
instead and do your own formatting as desired.badge_file
property has been removed.
- Now always groups results by namespace, even if a specific namespace was provided. Before, it only grouped by namespace if
- The
/api/user/top_edits
endpoint- Now returns the
full_page_title
property instead ofpage_title_ns
. - The
pa_class
property is replaced byassessment
, which has the keysclass
,badge
,color
andcategory
. - The
rev_deleted
property has been removed. - The
reverted
property is now a boolean instead of an integer. - The
minor
property is now a boolean instead of an integer.
- Now returns the
Errors
- All fatal errors (not warnings) are in the format specified by RFC 7807, with at minimum
status
,title
anddetails
properties. Warnings are still be an array under thewarning
property.