Edit API

action=edit creates new pages and modifies existing ones. It is implemented in ApiEditPage, which wraps the EditPage class. All edit requests must be sent as HTTP POST and must include a valid CSRF token.

action=edit is a write operation. You must be authenticated and possess a CSRF token before calling it. Unauthenticated edits are only possible on wikis that explicitly allow anonymous editing, and even then a token is required.

Required parameters

title

string

Title of the page to edit. Provide either title or pageid, not both.

pageid

integer

Page ID of the page to edit. Alternative to title.

token

string

required

CSRF token obtained from action=query&meta=tokens&type=csrf. The token is tied to the session; obtain a fresh token for each bot session, not each edit.

Content parameters

At least one of text, appendtext, prependtext, or undo must be provided (enforced by ApiEditPage::execute).

text

string

Full replacement text for the page. Replaces the entire content. Incompatible with appendtext and prependtext.

appendtext

string

Text to append to the end of the page (or section). Does not require knowledge of the current content.

prependtext

string

Text to prepend to the beginning of the page (or section).

section

string

Section identifier. 0 for the lead section, a positive integer for a numbered section, or new to append a new section. When section=new, sectiontitle sets the new section heading.

sectiontitle

string

Title for a new section. Only used when section=new.

Edit metadata

summary

string

Edit summary displayed in the page history and recent changes. Strongly recommended for all edits. If omitted when creating a new section, the section title is used as the summary.

minor

boolean

Mark the edit as minor. Only meaningful for logged-in users; the wiki may restrict who can set this flag.

notminor

boolean

Explicitly mark the edit as non-minor, overriding the user preference to default to minor edits.

bot

boolean

Mark the edit as a bot edit, hiding it from recent changes for users who filter bot edits. Requires the bot user right.

Conflict detection

To detect edit conflicts — where another editor changed the page between your read and your write — pass timestamps obtained before your edit:

basetimestamp

timestamp

Timestamp of the revision your edit is based on (from rvprop=timestamp). If the page was edited after this timestamp, the API returns an edit-conflict error.

starttimestamp

timestamp

Timestamp of when you fetched the page content (your local read time). Used together with basetimestamp to detect file upload conflicts.

baserevid

integer

Revision ID of the base revision, as an alternative to basetimestamp.

Creation control

createonly

boolean

Fail with articleexists if the page already exists. Useful for ensuring you are creating, not overwriting.

nocreate

boolean

Fail with missingtitle if the page does not already exist.

recreate

boolean

Suppress the error that would otherwise occur when editing a page over an existing deletion log entry.

Undo

undo

integer

Revision ID to undo. The API reconstructs the edit made by that revision and applies the inverse change.

undoafter

integer

Revision ID to undo back to (inclusive). Undoes all revisions from undo back to undoafter. Omit to undo only the single revision specified by undo.

Content model

contentformat

string

Serialization format of the text parameter (e.g., text/x-wiki for wikitext, text/plain, application/json). Defaults to the page’s current content model format.

contentmodel

string

Content model for the page (e.g., wikitext, json, css, javascript). Changing this also changes the content model of the page.

Complete edit workflow

Authenticate

Log in using a bot password. See Authentication for the full login flow. Store the session cookies for subsequent requests.

Fetch a CSRF token

Obtain a token with action=query&meta=tokens. Reuse this token for the entire session; do not fetch a new one per edit.

curl -b cookies.txt -c cookies.txt \
  "https://en.wikipedia.org/w/api.php?action=query&meta=tokens&type=csrf&format=json&formatversion=2"

Response:

{
  "query": {
    "tokens": {
      "csrftoken": "d41d8cd98f00b204e9800998ecf8427e+\\"
    }
  }
}

Fetch current content (optional but recommended)

For conflict-safe edits, retrieve the current revision and its timestamp before editing.

curl -b cookies.txt \
  "https://en.wikipedia.org/w/api.php?action=query&titles=Sandbox&prop=revisions&rvprop=ids|timestamp|content&rvslots=main&format=json&formatversion=2"

Record revisions[0].revid as your baserevid and revisions[0].timestamp as your basetimestamp.

Submit the edit

POST to action=edit with the token, content, and conflict-detection timestamps.

curl -b cookies.txt -c cookies.txt -X POST \
  "https://en.wikipedia.org/w/api.php" \
  --data-urlencode "action=edit" \
  --data-urlencode "title=Sandbox" \
  --data-urlencode "text=New content here." \
  --data-urlencode "summary=Updating sandbox via API" \
  --data-urlencode "basetimestamp=2024-01-15T10:30:00Z" \
  --data-urlencode "token=d41d8cd98f00b204e9800998ecf8427e+\\" \
  --data "format=json&formatversion=2"

Code examples

TOKEN=$(curl -s -b cookies.txt \
  "https://en.wikipedia.org/w/api.php?action=query&meta=tokens&format=json&formatversion=2" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['query']['tokens']['csrftoken'])")

curl -b cookies.txt -c cookies.txt -X POST \
  "https://en.wikipedia.org/w/api.php" \
  --data-urlencode "action=edit" \
  --data-urlencode "title=Project:Sandbox" \
  --data-urlencode "text==Test heading==\nThis is a test paragraph." \
  --data-urlencode "summary=API test edit" \
  --data-urlencode "bot=1" \
  --data-urlencode "token=$TOKEN" \
  --data "format=json&formatversion=2"

Successful response

{
  "edit": {
    "result": "Success",
    "pageid": 12345,
    "title": "Project:Sandbox",
    "contentmodel": "wikitext",
    "oldrevid": 987654,
    "newrevid": 987655,
    "newtimestamp": "2024-01-15T10:35:00Z",
    "watched": false
  }
}

edit.result

string

"Success" on success. Any other value indicates failure.

edit.newrevid

integer

Revision ID of the newly created revision.

edit.nochange

boolean

Present and true when the submitted text is identical to the current revision; no revision was created.

Appending and prepending

Use appendtext or prependtext to add content without knowing the full current page text. These parameters are especially useful for leaving messages on talk pages.

# Append a new section to a talk page
curl -b cookies.txt -X POST "https://en.wikipedia.org/w/api.php" \
  --data-urlencode "action=edit" \
  --data-urlencode "title=User_talk:Example" \
  --data-urlencode "section=new" \
  --data-urlencode "sectiontitle=Question about your edit" \
  --data-urlencode "appendtext=Hello, I had a question about your recent edit. ~~~~" \
  --data-urlencode "token=$TOKEN" \
  --data "format=json&formatversion=2"

Section editing

To edit a specific section, pass its index in section. Section 0 is always the lead section. Positive integers correspond to the section order in the wikitext.

curl -b cookies.txt -X POST "https://en.wikipedia.org/w/api.php" \
  --data-urlencode "action=edit" \
  --data-urlencode "title=MediaWiki" \
  --data-urlencode "section=2" \
  --data-urlencode "text=== Updated section text ==" \
  --data-urlencode "summary=Updated section 2" \
  --data-urlencode "token=$TOKEN" \
  --data "format=json&formatversion=2"

Undo a revision

curl -b cookies.txt -X POST "https://en.wikipedia.org/w/api.php" \
  --data-urlencode "action=edit" \
  --data-urlencode "title=MediaWiki" \
  --data-urlencode "undo=987654" \
  --data-urlencode "undoafter=987653" \
  --data-urlencode "summary=Undoing revision 987654" \
  --data-urlencode "token=$TOKEN" \
  --data "format=json&formatversion=2"

Error handling

Error code	Cause
`badtoken`	The CSRF token is invalid or expired
`edit-conflict`	Another edit occurred between your read and write; fetch fresh content and retry
`articleexists`	`createonly=1` was set but the page already exists
`missingtitle`	`nocreate=1` was set but the page does not exist
`noedit`	The page is protected and you lack the required permission
`noedit-anon`	Anonymous editing is not allowed on this wiki or page
`protectedpage`	The page is protected (see `inprop=protection` from `prop=info`)
`blocked`	Your account is blocked from editing
`ratelimited`	You have exceeded the edit rate limit; back off and retry

REST API

Action API

PHP Services

Required parameters

Content parameters

Edit metadata

Conflict detection

Creation control

Undo

Content model

Complete edit workflow

Code examples

Successful response

Appending and prepending

Section editing

Undo a revision

Error handling

Build docs developers (and LLMs) love

REST API

Action API

PHP Services

​Required parameters

​Content parameters

​Edit metadata

​Conflict detection

​Creation control

​Undo

​Content model

​Complete edit workflow

​Code examples

​Successful response

​Appending and prepending

​Section editing

​Undo a revision

​Error handling

Build docs developers (and LLMs) love

Required parameters

Content parameters

Edit metadata

Conflict detection

Creation control

Undo

Content model

Complete edit workflow

Code examples

Successful response

Appending and prepending

Section editing

Undo a revision

Error handling