API/Edit

<translate> POST request to edit a page.</translate>

API documentation[edit]

</translate>

Example[edit]

The sample code in this example is in Python.</translate> <translate> See <tvar name=1></tvar> for examples and responses in <tvar name=2></tvar>.</translate>

POST request[edit]

Making edits, and, indeed, any POST request, is a multi-step process. </translate>

1. <translate> Log in, via one of the methods described in <tvar name=1></tvar>.</translate> <translate> Note that while this is required to correctly attribute the edit to its author, many wikis do allow users to edit without registering or logging into an account.</translate>

2. <translate> GET a :</translate>

3. <translate> Send a POST request, with the CSRF token, to take action on a page:</translate>

<translate> The Response section below is for the final POST request, to take action on the page.</translate> <translate> See the pages on <tvar name=1></tvar> and <tvar name=2></tvar> for the intermediary JSON responses to earlier steps.</translate>

<translate> Also note that the tokens in the queries on this page are sample values.</translate> <translate> Actual tokens are unique to each login session and cross-site request.</translate> <translate> They are included only to demonstrate how to properly format queries.</translate>

Response[edit]

</translate>

<syntaxhighlight lang="json"> {

   "edit": {
       "result": "Success",
       "pageid": 94542,
       "title": "Wikipedia:Sandbox",
       "contentmodel": "wikitext",
       "oldrevid": 371705,
       "newrevid": 371707,
       "newtimestamp": "2018-12-18T16:59:42Z"
   }

} </syntaxhighlight>

Sample code[edit]

</translate>

/Sample code 1}}

User cases[edit]

Edit conflicts[edit]

</translate> <translate> The [[<tvar name=1>#Sample code</tvar>|Python sample]] is a basic implementation of an edit request by a registered user.</translate> <translate> In real-world scenarios, care should be taken to prevent edit conflicts.</translate> <translate> These occur when two or more users are attempting to edit the same page at the same time.</translate>

<translate> Conflicts can be prevented by retrieving the last timestamp when we request a CSRF token.</translate> <translate> Adding <tvar name=1>prop=info|revisions</tvar> to the CSRF token request in Step 3 allows us to access the timestamp for the last revision.</translate> <translate> This timestamp will be used as the <tvar name=1>basetimestamp</tvar> when we make our the edit request.</translate>

<translate> We also need the exact time when we start our edit.</translate> <translate> This can be retrieved by adding <tvar name=1>curtimestamp</tvar> to the CSRF request as well.</translate> <translate> This value will serve as our <tvar name=1>starttimestamp</tvar>.</translate>

<translate> Finally, in the actual edit request, set the <tvar name=1>basetimestamp</tvar> and <tvar name=2>starttimestamp</tvar> parameters, like so: </translate>

Large edits[edit]

</translate> <translate> POST requests containing large amounts of text content (8000+ characters) should be sent with <tvar name=1>Content-Type: multipart/form-data</tvar> indicated in the [[<tvar name=2>devmo:Web/HTTP/Headers</tvar>|header]].</translate> <translate> Because <tvar name=1>multipart/form-data</tvar> does not need to add HTML escape characters (i.e., [[<tvar name=2>devmo:Glossary/percent-encoding</tvar>|percent encoding]]) for spaces and punctuation, the amount of data passed will subsequently be much smaller than the percent-encoded equivalent.</translate>

<translate> However, there is still some overhead added by <tvar name=1>multipart/form-data</tvar> -- roughly, 160 bytes per parameter.</translate> <translate> For short messages that don't require adding many escape characters, this amount of overhead can be inefficient, and percent-encoding is preferred.</translate><ref> https://stackoverflow.com/a/4073451 </ref>

<translate> Note that in our [[<tvar name=1>#Example</tvar>|Python sample code]], the request is percent-encoded by default. </translate>

<translate> See [[<tvar name=1>devmo:Web/HTTP/Headers/Content-Type</tvar>|the MDN web docs]] for a more technical discussion of content-type and POST requests.</translate> <translate> See [<tvar name=url>http://docs.python-requests.org/en/master/user/quickstart/#more-complicated-post-requests</tvar> the Python Requests documentation] for how to pass <tvar name=1>multipart/form-data</tvar> using syntax similar to our Python sample code.</translate>

CAPTCHAs[edit]

</translate> <translate> If the wiki you are targeting uses , your request may return an error containing an ID number and a simple test, such as a question, a math problem, or a URL to an image.</translate> <translate> In order to complete your edit, you must complete the test, then retry your request with the id and the correct answer(s) appended to the original query string, like so:</translate> captchaid=sampleId&captchaword=answer

<translate> Other CAPTCHA systems and extensions may use different parameters for similar use.</translate> <translate> In general, use the field names for the ID and test questions as the parameters in your second request.</translate>

Possible errors[edit]

</translate>

<translate> Code</translate>	<translate> Info</translate>
notitle
missingparam	3}}
notoken
invalidsection
protectedpage	en \| \| }}
cantcreate
cantcreate-anon	<translate> Anonymous users can't create new pages</translate>
articleexists
noimageredirect-anon
noimageredirect
spamdetected
abusefilter-warning	<translate> This action has been automatically identified as harmful.</translate>
abusefilter-disallowed	<translate> This action has been automatically identified as harmful, and therefore disallowed.</translate>
contenttoobig	Where bytes is the value of .
noedit-anon
noedit
pagedeleted
emptypage
emptynewsection
editconflict
revwrongpage	<translate> Thrown if an invalid revid is given for <tvar name=undo>`undo`</tvar> or <tvar name=undoafter>`undoafter`</tvar></translate>
undofailure
missingtitle	<translate> (see above <tvar name=nocreate>`nocreate`</tvar> [[<tvar name=1>#Parameters</tvar>\|parameter]])</translate>
mustbeposted
readapidenied
writeapidenied
noapiwrite
badtoken
missingparam
invalidparammix
invalidtitle
invalid-content-data	<translate> occurs when trying to edit a JSON page with non-conforming data, or while trying to edit a <tvar name=1>MassMessageListContent</tvar> page</translate>
nosuchpageid
pagecannotexist
nosuchrevid
nosuchrevid
badmd5
hookaborted
parseerror
summaryrequired
blocked
ratelimited
unknownerror
nosuchsection
sectionsnotsupported
editnotsupported	<translate> Editing of this type of page is not supported using the text based edit API.</translate>
appendnotsupported
redirect-appendonly
edit-invalidredirect
badformat
customcssprotected
customjsprotected
taggingnotallowed	<translate> You don't have permission to set change tags</translate>
badtags	Tag2}}
tpt-target-page	<translate> When using <tvar name=translate></tvar>, editing of a translated subpage is not allowed.</translate>

Parameter history[edit]

</translate>

v1.35: <translate> Introduced <tvar name=1>baserevid</tvar></translate>
v1.25: <translate> Introduced <tvar name=1>tags</tvar></translate>
v1.21: <translate> Introduced <tvar name=1>contentformat, contentmodel</tvar></translate>
v1.20: <translate> Introduced <tvar name=1>pageid</tvar></translate>
v1.19: <translate> Introduced <tvar name=1>sectiontitle</tvar></translate>
v1.18: <translate> Deprecated <tvar name=1>captchaid, captchaword</tvar></translate>
v1.17: <translate> Introduced <tvar name=1>redirect</tvar></translate>
v1.16: <translate> Deprecated <tvar name=1>watch, unwatch</tvar></translate>
v1.16: <translate> Introduced <tvar name=1>watchlist</tvar></translate>
v1.15: <translate> Introduced <tvar name=1>undo, undoafter</tvar></translate>
v1.14: <translate> Introduced <tvar name=1>starttimestamp</tvar></translate>

Additional notes[edit]

Log in is not strictly required by the API, but it is needed to correctly attribute the edit to its author.</translate> <translate> A successful edit from a user who is not logged in will be attributed to their IP address.</translate>

Bots that are not logged in may face restrictions on editing and other write requests; see for more details.</translate>

Users who are not logged in will always be given the empty CSRF token, <tvar name=1>+\</tvar>.</translate>

The process for requesting a token has changed several times across versions.</translate> <translate> See <tvar name=1></tvar> for more information.</translate>

<tvar name=1></tvar> provides a way to access edit tokens when running code within a wiki page.</translate>

You can use the same CSRF token for all edit operations across the same wiki, during a single login session.</translate>

It is a good practice to pass any tokens in your request at the end of the query string, or at least after the text parameter.</translate> <translate> That way, if the connection is interrupted, the token will not be passed and the edit will fail.</translate> <translate> If you are using the <tvar name=1></tvar> object to make requests, this is done automatically.</translate>

Although <tvar name=1>captchaid</tvar> and <tvar name=2>captchaword</tvar> have, technically, been removed from API:Edit since v1.18, <tvar name=3></tvar> extends API:Edit to work with CAPTCHAs.</translate> <translate> Thus, with ConfirmEdit installed, these parameters are still available.</translate> <translate> ConfirmEdit comes packaged with the MediaWiki software, v1.18+.</translate>

Limitations[edit]

The API does not yet support editing content slots (). You can do so instead with an extension like Extension:WSSlots, which enables the editslot API action.

References[edit]

</translate>

Sample content adapted from mediawikiwiki:API:Edit on mediawiki.org, licensed under CC BY-SA 4.0.

API documentation[edit]

Example[edit]

POST request[edit]

Response[edit]

Sample code[edit]

User cases[edit]

Edit conflicts[edit]

Large edits[edit]

CAPTCHAs[edit]

Possible errors[edit]

Parameter history[edit]

Additional notes[edit]

Limitations[edit]

See also[edit]

References[edit]