API:REST API/Reference

From mediawiki.org
Jump to navigation Jump to search

The REST API lets you interact with MediaWiki by sending HTTP requests to unique URLs. You can use the API to build apps and scripts that search wiki pages and explore page history.

Search[edit]

MediaWiki version:
1.35

Search result object[edit]

The search result object represents a wiki page matching the requested search.

Example[edit]

{
  "id": 38930,
  "key": "Jupiter",
  "title": "Jupiter",
  "excerpt": "<span class=\"searchmatch\">Jupiter</span> is the fifth planet from the Sun and the largest in the Solar System. It is a gas giant with a mass one-thousandth that of the Sun, but two-and-a-half",
  "description": "fifth planet from the Sun and largest planet in the Solar System",
  "thumbnail": {
    "mimetype": "image/jpeg",
    "size": null,
    "width": 200,
    "height": 200,
    "duration": null,
    "url": "//upload.wikimedia.org/wikipedia/commons/thumb/2/2b/Jupiter_and_its_shrunken_Great_Red_Spot.jpg/200px-Jupiter_and_its_shrunken_Great_Red_Spot.jpg"
  }
}

Schema[edit]

id

required | integer

Page identifier
key

required | string

Page title in URL-friendly format
title

required | string

Page title in reading-friendly format
excerpt

required | string

For search pages endpoint:

A few lines giving a sample of page content with search terms highlighted with <span class=\"searchmatch\"> tags

For autocomplete page title endpoint:

Page title in reading-friendly format

description

required | string

Short summary of the page topic based on the corresponding entry on Wikidata or null if no entry exists
thumbnail

required | object

Information about the thumbnail image for the page or null if no thumbnail exists.
  • mimetype (string): Thumbnail media type
  • size (integer): File size in bytes or null if not available
  • width (integer): Maximum recommended image width in pixels or null if not available
  • height (integer): Maximum recommended image height in pixels or null if not available
  • duration (integer): Length of the video, audio, or multimedia file or null for other media types
  • url (string): URL to download the file

Search pages[edit]

Route /search/page?q=search terms Content type application/json
Method GET Returns pages object containing array of search results

Searches wiki page titles and contents for the provided search terms, and returns matching pages.

When using this endpoint on your wiki
This endpoint uses the search engine configured in the $wgSearchType configuration setting and returns results in the namespaces configured by $wgNamespacesToBeSearchedDefault.

Examples[edit]

curl[edit]

# Search English Wikipedia for up to 20 pages containing information about Jupiter
$ curl https://en.wikipedia.org/w/rest.php/v1/search/page?q=jupiter&limit=20

Python[edit]

# Search English Wikipedia for up to 20 pages containing information about Jupiter

import requests

search_query = 'jupiter'
number_of_results = 20
url = 'https://en.wikipedia.org/w/rest.php/v1/search/page'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers, params={'q': search_query, 'limit': number_of_results})
data = response.json()

print(data)

PHP[edit]

<?php
/*
Search English Wikipedia for up to 20 pages containing information about Jupiter
*/

$params = array("q" => "jupiter", "limit" => "20");

$endpoint = "https://en.wikipedia.org/w/rest.php/v1/search/page";
$url = $endpoint . "?" . http_build_query($params);

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Search English Wikipedia for up to 20 pages containing information about Jupiter
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/search/page?q=jupiter&limit=20",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

q

required | query

Search terms
limit

optional | query

Maximum number of search results to return, between 1 and 100. Default: 50

Responses[edit]

200 Success: Results found. Returns a pages object containing an array of search results.
200 Success: No results found. Returns a pages object containing an empty array.
400 Query parameter not set. Add q parameter.
400 Invalid limit requested. Set limit parameter to between 1 and 100.
500 Search error

Autocomplete page title[edit]

Route /search/title?q=search terms Content type application/json
Method GET Returns pages object containing array of search results

Searches wiki page titles, and returns matches between the beginning of a title and the provided search terms. You can use this endpoint for a typeahead search that automatically suggests relevant pages by title.

When using this endpoint on your wiki
This endpoint uses the search engine configured in the $wgSearchType configuration setting and returns results in the namespaces configured by $wgNamespacesToBeSearchedDefault. Results may differ depending on the configured search backend. While the default backend only applies basic case folding and prefix matches, more advanced backends may apply more complex variations. In the case of CirrusSearch for instance, matches are based on the Elastic Search completion suggester.

Examples[edit]

curl[edit]

# Search English Wikipedia for up to 5 pages with titles that start with "solar"
$ curl https://en.wikipedia.org/w/rest.php/v1/search/title?q=solar&limit=5

Python[edit]

# Search English Wikipedia for up to 5 pages with titles that start with "solar"

import requests

search_query = 'solar'
number_of_results = 5
url = 'https://en.wikipedia.org/w/rest.php/v1/search/title'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers, params={'q': search_query, 'limit': number_of_results})
data = response.json()

print(data)

PHP[edit]

<?php
/*
Search English Wikipedia for up to 5 pages with titles that start with "solar"
*/

$params = array("q" => "solar", "limit" => "5");

$endpoint = "https://en.wikipedia.org/w/rest.php/v1/search/title";
$url = $endpoint . "?" . http_build_query($params);

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Search English Wikipedia for up to 5 pages with titles that start with "solar"
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/search/title?q=solar&limit=5",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

q

required | query

Search terms
limit

optional | query

Maximum number of search results to return, between 1 and 100. Default: 50

Responses[edit]

200 Success: Results found. Returns a pages object containing an array of search results.
200 Success: No results found. Returns a pages object containing an empty array.
400 Query parameter not set. Add q parameter.
400 Invalid limit requested. Set limit parameter to between 1 and 100.
500 Search error

Pages[edit]

MediaWiki version:
1.35

Page object[edit]

The page object represents the latest revision of a wiki page.

Example[edit]

{
  "id": 9228,
  "key": "Earth",
  "title": "Earth",
  "latest": {
    "id": 963613515,
    "timestamp": "2020-06-20T20:05:55Z"
  },
  "content_model": "wikitext",
  "license": {
    "url": "//creativecommons.org/licenses/by-sa/3.0/",
    "title": "Creative Commons Attribution-Share Alike 3.0"
  },
  "html_url": "https://en.wikipedia.org/w/rest.php/v1/page/Earth/html"
}

Schema[edit]

id

required | integer

Page identifier
key

required | string

Page title in URL-friendly format
title

required | string

Page title in reading-friendly format
latest

required | object

Information about the latest revision, including:
  • id (integer): Revision identifier for the latest revision
  • timestamp (string): Timestamp of the latest revision in ISO 8601 format
content_model

required | string

Type of content on the page. See the content handlers reference for content models supported by MediaWiki and extensions.
license

required | map of strings

Information about the wiki's license, including:
  • url (string): URL of the applicable license based on the $wgRightsUrl setting
  • title (string): Name of the applicable license based on the $wgRightsText setting
Get page only

html_url

required | string

API route to fetch the content of the page in HTML
Get page offline only

html

required | string

Latest page content in HTML, following the HTML 2.1.0 specification
Get page source, create page, and update page only

source

required | string

Latest page content in the format specified by the content_model property

Page language object[edit]

The page language object represents a wiki page and its language.

Example[edit]

{
  "code": "pl",
  "name": "polski",
  "key": "Ziemia",
  "title": "Ziemia"
}

Schema[edit]

code

required | string

Language code. For Wikimedia projects, see the site matrix on Meta-Wiki.
name

required | string

Translated language name
key

required | string

Translated page title in URL-friendly format
title

required | string

Translated page title in reading-friendly format

Create page[edit]

Route /page Content type application/json
Method POST Returns Page object with source property

Creates a wiki page. The response includes a location header containing the API endpoint to fetch the new page.

This endpoint is designed to be used with the OAuth extension authorization process. Callers using cookie-based authentication instead must add a CSRF token to the request body. To get a CSRF token, see the Action API.

Examples[edit]

curl[edit]

# Create a user sandbox page on English Wikipedia
$ curl -X POST https://en.wikipedia.org/w/rest.php/v1/page -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" --data '{"source": "Hello, world!", "title": "User:<my username>/Sandbox", "comment": "Creating a test page with the REST API"}'

Python[edit]

# Create a user sandbox page on English Wikipedia
import requests
import json

url = 'https://en.wikipedia.org/w/rest.php/v1/page'

# Substitute your OAuth token
headers = {
    'User-Agent'   : 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)',
    'Content-Type' : 'application/json',
    'Authorization': 'Bearer $TOKEN'
}

# Substitute your username
request_data = {
    "source" : "Hello, world!",
    "title"  : "User:<my username>/Sandbox",
    "comment": "Creating a test page with the REST API"
}

response = requests.post( url, headers=headers, data = json.dumps(request_data) )
output = response.json()

print(output)

PHP[edit]

<?php
/*
Create a user sandbox page on English Wikipedia
*/

$url = 'https://en.wikipedia.org/w/rest.php/v1/page';

// Substitute your username
$fields = [
    'source' => 'Hello, world!',
    'title' => 'User:<my username>/Sandbox',
    'comment' => 'Creating a test page with the REST API'
];

$json = json_encode( $fields );

$token = 'YOUR_OAUTH_TOKEN'; // Substitute your OAuth token
$authorization = 'Authorization: Bearer ' . $token;

$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json' , $authorization ));
curl_setopt( $ch, CURLOPT_USERAGENT, 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)' );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );

$output = curl_exec( $ch );
curl_close( $ch );

echo( $output );
?>

JavaScript[edit]

/*  
    Create a user sandbox page on English Wikipedia

    Substitute your OAuth token for $TOKEN.
    Substitute your username for <my username>.
*/

async function doFetch() {
  const response = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page",
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $TOKEN'
      },
      body: JSON.stringify({
        "source" : "Hello, world!",
        "title"  : "User:<my username>/Sandbox",
        "comment": "Creating a test page with the REST API"
      }),
      'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'
    }
  );
  const data = await response.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Request schema[edit]

source

required | string

Page content in the format specified by the content_model property
title

required | string

Page title. See the manual for information about page titles in MediaWiki.
comment

required | string

Reason for creating the page. To allow the comment to be filled in by the server, use "comment": null.
content_model

optional | string

Type of content on the page. Defaults to wikitext. See the content handlers reference for content models supported by MediaWiki and extensions.
token

optional | string

CSRF token required when using cookie-based authentication. Omit this property when authorizing using OAuth.

Responses[edit]

201 Success: Page created. Returns page object with source property.
400 Missing token when using cookie-based authentication. Add a CSRF token to the request body, or use an OAuth authorization flow.
400 Bad content model. Include a valid content_model based on available content handlers.
409 Page already exists
415 Unsupported Content-Type. Add the request header Content-Type: application/json.

Update page[edit]

Route /page/{title} Content type application/json
Method PUT Returns Page object with source property

Updates or creates a wiki page. This endpoint is designed to be used with the OAuth extension authorization process. Callers using cookie-based authentication instead must add a CSRF token to the request body. To get a CSRF token, see the Action API.

To update a page, you need the page's latest revision ID and the page source. First call the get page source endpoint, and then use the source and latest.id to update the page. If latest.id doesn't match the page's latest revision, the API resolves conflicts automatically when possible. In the event of an edit conflict, the API returns a 409 error.

To create a page, omit latest.id from the request.

Examples[edit]

curl[edit]

# Update the sandbox page on English Wikipedia with "Hello, world!"
$ curl -X PUT https://en.wikipedia.org/w/rest.php/v1/page/Wikipedia:Sandbox -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" --data '{"source": "Hello, world!", "comment": "Testing out the REST API", "latest": { "id": 555555555 }}'

Python[edit]

# Update the sandbox page on English Wikipedia with "Hello, world!"
import requests
import json

url = "https://en.wikipedia.org/w/rest.php/v1/page/Wikipedia:Sandbox"

# Substitute your OAuth token
headers = {
    "User-Agent" : "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)",
    "Content-Type" : "application/json",
    "Authorization" : "Bearer $TOKEN"
}

# Use the get page endpoint to get the latest revision ID
request_data = {
    "source" : "Hello, world!",
    "comment": "Testing out the REST API",
    "latest" : { "id": 555555555 }
}

response = requests.put( url, headers=headers, data = json.dumps(request_data) )
output = response.json()

print(output)

PHP[edit]

<?php
/*
Update the sandbox page on English Wikipedia with "Hello, world!"
*/

$page = 'Wikipedia:Sandbox';
$endpoint = 'https://en.wikipedia.org/w/rest.php/v1/page/';
$url = $endpoint . $page;

// Use the get page endpoint to get the latest revision ID
$fields = [
    'source' => 'Hello, world!',
    'comment' => 'Testing out the REST API',
    'latest' => [
        'id' => 555555555
    ]
];

$json = json_encode( $fields );

$token = 'YOUR_OAUTH_TOKEN'; // Substitute your OAuth token
$authorization = 'Authorization: Bearer ' . $token;

$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'PUT' );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json' , $authorization ));
curl_setopt( $ch, CURLOPT_USERAGENT, 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)' );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); 

$output = curl_exec( $ch );
curl_close( $ch );

echo( $output );
?>

JavaScript[edit]

/*  
    Update the sandbox page on English Wikipedia with "Hello, world!"

    Substitute your OAuth token for $TOKEN.
    Use the get page endpoint to get the latest revision ID.
*/

async function doFetch() {
  const response = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Wikipedia:Sandbox",
    {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $TOKEN'
      },
      body: JSON.stringify({
        "source": "Hello, world!",
        "comment": "Testing out the REST API",
        "latest": { "id": 555555555 }
      }),
      'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'
    }
  );
  const data = await response.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Parameters[edit]

title

required | path

Wiki page title

Request schema[edit]

source

required | string

Page content in the format specified by the content_model property
comment

required | string

Summary of the edit. To allow the comment to be filled in by the server, use "comment": null.
latest

optional | object

Object identifying the base revision of the edit. You can fetch this information from the get page source endpoint.
latest.id

optional | integer

Identifier for the revision used as the base for the new source, required for updating an existing page. To create a page, omit this property.
content_model

optional | string

Type of content on the page. Defaults to wikitext for new pages or to the existing page's content model. See the content handlers reference for content models supported by MediaWiki and extensions.
token

optional | string

CSRF token required when using cookie-based authentication. Omit this property when authorizing using OAuth.

Responses[edit]

200 Success: Page updated. Returns page object with source property.
201 Success: Page created. Returns page object with source property.
400 Missing token when using cookie-based authentication. Add a CSRF token to the request body, or use an OAuth authorization flow.
400 Bad content model. Ensure that the content_model property in the request body matches the content_model for the target page.
409 Page already exists. To update the existing page, provide the base revision identifier in latest.id in the request body.
409 Edit conflict. The error response includes the differences between the base revision specified in the request and the latest published revision. See the Wikidiff2 docs for information about the diff format. Requires Wikidiff2 extension 1.10+.
415 Unsupported Content-Type. Add the request header Content-Type: application/json.

Get page[edit]

Route /page/{title}/bare Content type application/json
Method GET Returns Page object with html_url property

Returns the standard page object for a wiki page, including the API route to fetch the latest content in HTML, the license, and information about the latest revision.

To use this endpoint on your wiki
Install RESTBase and configure VirtualRESTService.

Examples[edit]

curl[edit]

# Get information about the Jupiter article on English Wikipedia
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/bare

Python[edit]

# Get information about the Jupiter article on English Wikipedia

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/bare'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get information about the Jupiter article on English Wikipedia
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/bare";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get information about the Jupiter article on English Wikipedia
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/bare",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success: Page found. Returns page with html_url property.
404 Title or revision not found
500 RESTBase not installed or not configured with VirtualRESTService

Get page offline[edit]

Route /page/{title}/with_html Content type application/json
Method GET Returns Page object with html property

Returns information about a wiki page, including the license, latest revision, and latest content in HTML.

To use this endpoint on your wiki
Install RESTBase and configure VirtualRESTService.

Examples[edit]

curl[edit]

# Get HTML and metadata for the Jupiter article on English Wikipedia
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/with_html

Python[edit]

# Get HTML and metadata for the Jupiter article on English Wikipedia

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/with_html'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get HTML and metadata for the Jupiter article on English Wikipedia
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/with_html";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get HTML and metadata for the Jupiter article on English Wikipedia
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/with_html",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success: Page found. Returns page with html property.
404 Title or revision not found
500 RESTBase not installed or not configured with VirtualRESTService

Get page source[edit]

Route /page/{title} Content type application/json
Method GET Returns Page object with source property

Returns the content of a wiki page in the format specified by the content_model property, the license, and information about the latest revision.

Examples[edit]

curl[edit]

# Get source and metadata for the Jupiter article on English Wikipedia
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter

Python[edit]

# Get source and metadata for the Jupiter article on English Wikipedia

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get source and metadata for the Jupiter article on English Wikipedia
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page;

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get source and metadata for the Jupiter article on English Wikipedia
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success: Page found. Returns page with source property.
400 The page you requested is not supported by this endpoint
404 Content doesn't exist or cannot be loaded

Get HTML[edit]

Route /page/{title}/html Content type text/html
Method GET Returns Page HTML in HTML 2.1.0 format

Returns the latest content of a wiki page in HTML.

To use this endpoint on your wiki
Install RESTBase and configure VirtualRESTService.

Examples[edit]

curl[edit]

# Get the content of the Jupiter article on English Wikipedia in HTML
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/html

Python[edit]

# Get the content of the Jupiter article on English Wikipedia in HTML

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/html'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
print(response.text)

PHP[edit]

<?php
/*
Get the content of the Jupiter article on English Wikipedia in HTML
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/html";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get the content of the Jupiter article on English Wikipedia in HTML
*/

async function doFetch() {
  const response = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/html",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await response.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success. Returns page HTML in HTML 2.1.0 format.
404 Title or revision not found
500 RESTBase not installed or not configured with VirtualRESTService

Get languages[edit]

Route /page/{title}/links/language Content type application/json
Method GET Returns Array of page languages

Searches connected wikis for pages with the same topic in different languages. Returns an array of page language objects that include the name of the language, the language code, and the translated page title.

Examples[edit]

curl[edit]

# Find articles from other Wikipedias linked to the Jupiter article on English Wikipedia
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/links/language

Python[edit]

# Find articles from other Wikipedias linked to the Jupiter article on English Wikipedia

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/links/language'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Find articles from other Wikipedias linked to the Jupiter article on English Wikipedia
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/links/language";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Find articles from other Wikipedias linked to the Jupiter article on English Wikipedia
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/links/language",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success: Languages found. Returns array of page languages.
404 Title not found

Get files on page[edit]

Route /page/{title}/links/media Content type application/json
Method GET Returns files object containing array of files

Returns information about media files used on a wiki page.

Examples[edit]

curl[edit]

# Get media files used on the Jupiter article on English Wikipedia
$ curl https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/links/media

Python[edit]

# Get media files used on the Jupiter article on English Wikipedia

import requests

page = 'Jupiter'
url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/links/media'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get media files used on the Jupiter article on English Wikipedia
*/

$page = "Jupiter";
$url = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/links/media";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get media files used on the Jupiter article on English Wikipedia
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/links/media",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title

Responses[edit]

200 Success: Media files found. Returns files object containing array of files.
200 Success: No media files found. Returns files object containing an empty array.
404 Title not found
500 Page contains more than 500 media files

Media files[edit]

MediaWiki version:
1.35

File object[edit]

The file object represents a file uploaded to a wiki.

Example[edit]

{
  "title": "The Blue Marble.jpg",
  "file_description_url": "//commons.wikimedia.org/wiki/File:The_Blue_Marble.jpg",
  "latest": {
    "timestamp": "2011-12-07T05:11:41Z",
    "user": {
      "id": 811185,
      "name": "Ultimate Roadgeek"
    }
  },
  "preferred": {
    "mediatype": "BITMAP",
    "size": null,
    "width": 599,
    "height": 599,
    "duration": null,
    "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/78/The_Blue_Marble.jpg/599px-The_Blue_Marble.jpg"
  },
  "original": {
    "mediatype": "BITMAP",
    "size": 7011595,
    "width": 3000,
    "height": 3002,
    "duration": null,
    "url": "https://upload.wikimedia.org/wikipedia/commons/7/78/The_Blue_Marble.jpg"
  },
  "thumbnail": {
    "mediatype": "BITMAP",
    "size": null,
    "width": 1023,
    "height": 1024,
    "duration": null,
    "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/78/The_Blue_Marble.jpg/1023px-The_Blue_Marble.jpg"
  }
}

Schema[edit]

title

required | string

File title
file_description_url

required | string

URL for the page describing the file, including license information and other metadata
latest

required | object

Object containing information about the latest revision to the file, including:
  • timestamp (string): Last modified timestamp in ISO 8601 format format
  • user (object): Object containing information about the user who uploaded the file
    • id (integer): User identifier
    • name (string): Username
preferred

required | object

Information about the file's preferred preview format, original format, and thumbnail format, including:
  • mediatype (string): The file type, one of: BITMAP, DRAWING, AUDIO, VIDEO, MULTIMEDIA, UNKNOWN, OFFICE, TEXT, EXECUTABLE, ARCHIVE, or 3D
  • size (integer): File size in bytes or null if not available
  • width (integer): Maximum recommended image width in pixels or null if not available
  • height (integer): Maximum recommended image height in pixels or null if not available
  • duration (integer): The length of the video, audio, or multimedia file or null for other media types
  • url (string): URL to download the file
original

required | object

Get file only

thumbnail

required | object

Get file[edit]

Route /file/{title} Content type application/json
Method GET Returns File

Returns information about a file, including links to download the file in thumbnail, preview, and original formats.

Examples[edit]

curl[edit]

# Get File:The_Blue_Marble.jpg on Wikimedia Commons
$ curl https://commons.wikimedia.org/w/rest.php/v1/file/File:The_Blue_Marble.jpg

Python[edit]

# Get File:The_Blue_Marble.jpg on Wikimedia Commons

import requests

file = 'File:The_Blue_Marble.jpg'
url = 'https://commons.wikimedia.org/w/rest.php/v1/file/' + file
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get File:The_Blue_Marble.jpg on Wikimedia Commons
*/

$file = "File:The_Blue_Marble.jpg";
$url = "https://commons.wikimedia.org/w/rest.php/v1/file/" . $file;

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get File:The_Blue_Marble.jpg on Wikimedia Commons
*/

async function doFetch() {
  const rsp = await fetch(
    "https://commons.wikimedia.org/w/rest.php/v1/file/File:The_Blue_Marble.jpg",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

parameter description
title

required | path

File title

Responses[edit]

200 Success: file found. Returns file.
404 Title not found

History[edit]

MediaWiki version:
1.35

Revision object[edit]

The revision object represents a change to a wiki page.

Example[edit]

{
  "id": 931281281,
  "page": {
    "id": 38930,
    "title": "Jupiter"
  },
  "size": 126009,
  "minor": false,
  "timestamp": "2019-12-18T01:39:24Z",
  "user": {
    "id": 27015025,
    "name": "InternetArchiveBot"
  },
  "comment": "Bluelinking 2 books for [[WP:V|verifiability]].) #IABot (v2.1alpha3",
  "delta": 231
}

Schema[edit]

id

required | integer

Revision identifier
Get revision only

page

required | object

Object containing information about the page, including:
  • page_id (integer): Page identifier
  • title (string): Page title in reading-friendly format
user

required | object

Object containing information about the user that made the edit, including:
  • name (string): Username
  • id (integer): User identifier

For anonymous users, the name contains the originating IP address, and the id is null.

timestamp

required | string

Time of the edit in ISO 8601 format
comment

required | string

Comment or edit summary written by the editor. For revisions without a comment, the API returns null or "".
size

required | integer

Size of the revision in bytes
delta

required | integer

Number of bytes changed, positive or negative, between a revision and the preceding revision (example: -20). If the preceding revision is unavailable, the API returns null.
minor

required | boolean

Set to true for edits marked as minor

Get page history[edit]

Route /page/{title}/history Content type application/json
Method GET Returns Page history segment

Returns information about the latest revisions to a wiki page, in segments of 20 revisions, starting with the latest revision. The response includes API routes for the next oldest, next newest, and latest revision segments, letting you scroll through page history.

Examples[edit]

curl[edit]

# Get revisions made to the Jupiter article on English Wikipedia by bots prior to revision 939967546
$ curl "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/history?filter=bot&older_than=939967546"

Python[edit]

# Get revisions made to the Jupiter article on English Wikipedia by bots prior to revision 939967546

import requests

page = 'Jupiter'
filter = 'bot'
older_than = 939967546

url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/history'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers, params={'filter': filter, 'older_than': older_than})
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get revisions made to the Jupiter article on English Wikipedia by bots prior to revision 939967546
*/

$page = "Jupiter";
$params = array("filter" => "bot", "older_than" => "939967546");

$endpoint = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/history";
$url = $endpoint . "?" . http_build_query($params);

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get revisions made to the Jupiter article on English Wikipedia by bots prior to revision 939967546
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/history?filter=bot&older_than=939967546",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title
older_than

optional | query

Accepts a revision ID. Returns the next 20 revisions older than the given revision ID.
newer_than

optional | query

Accepts a revision ID. Returns the next 20 revisions newer than the given revision ID.
filter

optional | query

Filter that returns only revisions with certain tags, one of:
  • reverted: Returns only revisions that revert an earlier edit
  • anonymous: Returns only revisions made by anonymous users
  • bot: Returns only revisions made by bots
  • minor: Returns only revisions marked as minor edits

The API supports one filter per request.

Responses[edit]

200 Success: Revisions found. Returns a page history segment.
200 Success: No revisions found. Returns a page history segment with an empty revisions array.
400 Revision identifier must be greater than 0
400 Parameters older_than and newer_than cannot both be specified
400 Invalid parameter
404 Title or revision not found

Response schema[edit]

latest

required | string

API route to get the latest revisions
older

optional | string

If available, API route to get the prior revisions
newer

optional | string

If available, API route to get the following revisions
revisions

required | array

Array of 0-20 revision objects

Get page history counts[edit]

Route /page/{title}/history/counts/{type} Content type application/json
Method GET Returns History count object

Returns data about a page's history.

Examples[edit]

curl[edit]

# Get the number of edits to a page between revisions 384955912 and 406217369
$ curl "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/history/counts/edits?from=384955912&to=406217369"

Python[edit]

# Get the number of edits to a page between revisions 384955912 and 406217369

import requests

page = 'Jupiter'
from_revision = 384955912
to_revision = 406217369

url = 'https://en.wikipedia.org/w/rest.php/v1/page/' + page + '/history/counts/edits'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers, params={'from': from_revision, 'to': to_revision})
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get the number of edits to a page between revisions 384955912 and 406217369
*/

$page = "Jupiter";
$count_type = "edits";
$params = array("from" => 384955912, "to" => 406217369);

$endpoint = "https://en.wikipedia.org/w/rest.php/v1/page/" . $page . "/history/counts/" . $count_type;
$url = $endpoint . "?" . http_build_query($params);

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get the number of edits to a page between revisions 384955912 and 406217369
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/page/Jupiter/history/counts/edits?from=384955912&to=406217369",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

title

required | path

Wiki page title
type

required | path

Type of count, one of:
  • anonymous: Edits made by anonymous users. Limit: 10,000
  • bot: Edits made by bots. Limit: 10,000
  • editors: Users or bots that have edited a page. Limit: 25,000
  • edits: Any change to page content. Limit: 30,000
  • minor: Edits marked as minor. If the minor edit count exceeds 2,000, the API returns a 500 error. Limit: 1,000
  • reverted: Edits that revert an earlier edit. Limit: 30,000
from

optional | query

For edits and editors types only

Restricts the count to between two revisions, specified by revision ID. The from and to query parameters must be used as a pair. The result excludes the edits or editors represented by the from and to revisions.

to

optional | query

Responses[edit]

200 Success
400 Invalid parameter or combination of parameters
404 Title or revision not found
500 Minor edit count exceeds 2000

Response schema[edit]

count

required | integer

The value of the data point up to the type's limit. If the value exceeds the limit, the API returns the limit as the value of count and sets the limit property to true.
limit

required | boolean

Returns true if the data point exceeds the type's limit.

Get revision[edit]

Route revision/{id}/bare Content type application/json
Method GET Returns Revision

Returns details for an individual revision.

Examples[edit]

curl[edit]

# Get information about revision 764138197
$ curl https://en.wikipedia.org/w/rest.php/v1/revision/764138197/bare

Python[edit]

# Get information about revision 764138197

import requests

revision_id = '764138197'

url = 'https://en.wikipedia.org/w/rest.php/v1/revision/' + revision_id + '/bare'
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Get information about revision 764138197
*/

$revision  = "764138197";

$url = "https://en.wikipedia.org/w/rest.php/v1/revision/" . $revision . "/bare";

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Get information about revision 764138197
*/

async function doFetch() {
  const rsp = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/revision/764138197/bare",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await rsp.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

id

required | path

Revision ID

Responses[edit]

200 Success: Revision found. Returns a revision.
404 Revision not found

Compare revisions[edit]

Route revision/{from}/compare/{to} Content type application/json
Methods GET Returns Wikidiff2 JSON diff format

Returns data that lets you display a line-by-line comparison of two revisions. (See an example.) Only text-based wiki pages can be compared.

To use this endpoint on your wiki
Install Extension:Wikidiff2 1.9.0 or later.

Examples[edit]

curl[edit]

# Compare revision 847170467 to 851733941
$ curl https://en.wikipedia.org/w/rest.php/v1/revision/847170467/compare/851733941

Python[edit]

# Compare revision 847170467 to 851733941

import requests

from_revision = '847170467'
to_revision = '851733941'

url = 'https://en.wikipedia.org/w/rest.php/v1/revision/' + from_revision + '/compare/' + to_revision
headers = {'User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

PHP[edit]

<?php
/*
Compare revision 847170467 to 851733941
*/

$from = "847170467";
$to = "851733941";

$url = "https://en.wikipedia.org/w/rest.php/v1/revision/" . $from . "/compare/" . $to;

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_USERAGENT, "MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)" );
$output = curl_exec( $ch );
curl_close( $ch );

echo($output);
?>

JavaScript[edit]

/*  
    Compare revision 847170467 to 851733941
*/

async function doFetch() {
  const response = await fetch(
    "https://en.wikipedia.org/w/rest.php/v1/revision/847170467/compare/851733941",
    {'Api-User-Agent': 'MediaWiki REST API docs examples/0.1 (https://www.mediawiki.org/wiki/API_talk:REST_API)'}
  );
  const data = await response.json();
  return data;
}

async function fetchAsync()
{
  try {
    let result = await doFetch();
    console.log(result);
  } catch( err ) {
    console.error( err.message );
  }
}

fetchAsync();

Try it out

Parameters[edit]

from

required | path

Revision identifier to use as the base for comparison
to

required | path

Revision identifier to compare to the base

Responses[edit]

200 Success: Revisions found
400 Revision IDs are for different pages or for pages that can't be compared
400 Invalid content type
403 Revision not publicly accessible
404 Revision not found
500 Wikidiff2 extension 1.9.0 or later not installed

Response schema[edit]

from

required | object

Information about the base revision used in the comparison
to

required | object

Information about the revision being compared to the base revision
from.id

to.id
required | integer

Revision identifier
from.slot_role

to.slot_role
required | string

Area of the page being compared, usually main
from.sections

to.sections
required | array

Array of objects representing section headings, including:
  • level (integer): Heading level, 1 through 4
  • heading (string): Text of the heading line, in wikitext
  • offset (integer): Location of the heading, in bytes from the beginning of the page


diff

required | array of objects

Each object in the diff array represents a line in a visual, line-by-line comparison between the two revisions.
diff.type

required | integer

The type of change represented by the diff object, either:
  • 0: A line with the same content in both revisions, included to provide context when viewing the diff. The API returns up to two context lines around each change.
  • 1: A line included in the to revision but not in the from revision.
  • 2: A line included in the from revision but not in the to revision.
  • 3: A line containing text that differs between the two revisions. (For changes to paragraph location as well as content, see type 5.)
  • 4: When a paragraph's location differs between the two revisions, a type 4 object represents the location in the from revision.
  • 5: When a paragraph's location differs between the two revisions, a type 5 object represents the location in the to revision. This type can also include word-level differences between the two revisions.
diff.lineNumber

optional | integer

The line number of the change based on the to revision.
diff.text

required | string

The text of the line, including content from both revisions. For a line containing text that differs between the two revisions, you can use highlightRanges to visually indicate added and removed text. For a line containing a new line, the API returns the text as "" (empty string).
diff.highlightRanges

optional | array of objects

An array of objects that indicate where and in what style text should be highlighted to visually represent changes.

Each object includes:

  • start (integer): Where the highlighted text should start, in the number of bytes from the beginning of the line.
  • length (integer): The length of the highlighted section, in bytes.
  • type (integer): The type of highlight:
    • 0 indicates an addition.
    • 1 indicates a deletion.
diff.moveInfo

optional | object

Visual indicators to use when a paragraph's location differs between the two revisions. moveInfo objects occur in pairs within the diff.
  • id (string): The ID of the paragraph described by the diff object.
  • linkId (string): The ID of the corresponding paragraph.
    • For type 4 diff objects, linkId represents the location in the to revision.
    • For type 5 diff objects, linkId represents the location in the from revision.
  • linkDirection (integer): A visual indicator of the relationship between the two locations. You can use this property to display an arrow icon within the diff.
    • 0 indicates that the linkId paragraph is lower on the page than the id paragraph.
    • 1 indicates that the linkId paragraph is higher on the page than the id paragraph.
diff.offset

required | object

The location of the line in bytes from the beginning of the page, including:
  • from (integer): The first byte of the line in the from revision. A null value indicates that the line doesn't exist in the from revision.
  • to (integer): The first byte of the line in the to revision. A null value indicates that the line doesn't exist in the to revision.