Wikivoyage Authentication API

openapi: 3.0.3
info:
  title: Wikivoyage MediaWiki Action Authentication API
  description: 'The MediaWiki Action API is the primary programmatic interface for Wikivoyage, exposed at https://en.wikivoyage.org/w/api.php. All operations dispatch via the ?action= query parameter. The API supports JSON, XML, and PHP serialization; JSON is the recommended format.


    Wikivoyage covers travel destinations worldwide and the Action API enables retrieval of travel destination articles, accommodation listings, sightseeing information, and practical travel advice. Supports both anonymous reads and authenticated writes via OAuth 2.0.


    Wikimedia Foundation API guidelines require a contactable User-Agent header, serial (not parallel) calls for bulk work, and the maxlag parameter for automated clients.'
  version: '1.47'
  x-generated-from: documentation
  x-source-url: https://www.mediawiki.org/wiki/API:Main_page
  x-last-validated: '2026-06-13'
  contact:
    name: Wikimedia Foundation
    url: https://www.mediawiki.org/wiki/API:Etiquette
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://en.wikivoyage.org/w
  description: English Wikivoyage
- url: https://{lang}.wikivoyage.org/w
  description: Per-language Wikivoyage
  variables:
    lang:
      default: en
      description: Language code (en, de, fr, es, it, pt, ru, zh, ...)
tags:
- name: Authentication
  description: Login, logout, token retrieval (action=login, clientlogin, logout, query&meta=tokens)
paths:
  /api.php:
    post:
      operationId: callActionApiPost
      summary: Wikivoyage MediaWiki Action API Dispatch (POST)
      description: Generic dispatch endpoint for write operations on Wikivoyage. Use ?action=edit to create/modify travel guide articles, ?action=upload for images, ?action=login or ?action=clientlogin to authenticate. All write operations require a CSRF token from action=query&meta=tokens. POSTs are not cached - use them for writes only.
      tags:
      - Authentication
      parameters:
      - name: action
        in: query
        required: true
        schema:
          type: string
          enum:
          - edit
          - upload
          - login
          - clientlogin
          - logout
          - patrol
          - rollback
          - move
          - delete
          - protect
          - block
          - unblock
          - thank
          - createaccount
          - emailuser
          - managetags
          - tag
          - options
          example: edit
      - name: format
        in: query
        required: true
        schema:
          type: string
          enum:
          - json
          - jsonfm
          - xml
          - xmlfm
          default: json
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ActionApiWriteRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ActionApiWriteRequest'
            description: Use multipart for action=upload
      responses:
        '200':
          description: Action result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResult'
        '401':
          description: Authentication required or invalid token
        '403':
          description: Permission denied
        '429':
          description: Rate limited
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ActionResult:
      type: object
      description: Generic envelope for Action API responses. Concrete payload shape depends on action and prop/list/meta selection.
      properties:
        batchcomplete:
          type: string
          description: Present when the batch completed in one round-trip
        continue:
          type: object
          description: Continuation tokens for paginated responses
        query:
          type: object
          description: Result body for action=query
        parse:
          type: object
          description: Result body for action=parse
        edit:
          type: object
          description: Result body for action=edit
        login:
          type: object
          description: Result body for action=login
        error:
          $ref: '#/components/schemas/ActionApiError'
        warnings:
          type: object
    ActionApiError:
      type: object
      properties:
        code:
          type: string
          example: ratelimited
        info:
          type: string
          description: Human-readable error description
        '*':
          type: string
          description: Legacy error text
        docref:
          type: string
          description: Pointer to docs for this error class
    ActionApiWriteRequest:
      type: object
      required:
      - token
      properties:
        title:
          type: string
          description: Travel article title for edit/move/delete/protect
        pageid:
          type: integer
          description: Alternative to title
        text:
          type: string
          description: Full wikitext content for action=edit
        appendtext:
          type: string
        prependtext:
          type: string
        summary:
          type: string
          description: Edit summary
        token:
          type: string
          description: CSRF token from query&meta=tokens
        basetimestamp:
          type: string
          format: date-time
          description: Timestamp of base revision for edit conflict detection
        starttimestamp:
          type: string
          format: date-time
        bot:
          type: boolean
          description: Mark as bot edit (requires bot right)
        minor:
          type: boolean
        recreate:
          type: boolean
        createonly:
          type: boolean
        nocreate:
          type: boolean
        lgname:
          type: string
          description: Login username (action=login)
        lgpassword:
          type: string
          description: Login password (action=login)
        lgtoken:
          type: string
          description: Login token
        filename:
          type: string
          description: Destination filename for action=upload
        file:
          type: string
          format: binary
          description: File contents for action=upload (multipart)
        url:
          type: string
          format: uri
          description: Source URL for action=upload (sideload)
        comment:
          type: string
          description: Upload comment
        tags:
          type: string
          description: Pipe-separated change tags
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token from meta.wikimedia.org
    CookieAuth:
      type: apiKey
      in: cookie
      name: wikivoyagewikiUserID
      description: Session cookie obtained via action=login or action=clientlogin