openapi: 3.0.3
info:
  title: Wiktionary Wikimedia REST API
  description: >-
    The Wikimedia REST API (RESTBase) exposed per-project at /api/rest_v1/.
    English Wiktionary publishes a Wiktionary-specific extension that returns
    structured multilingual definitions (/page/definition/{term}), alongside
    generic page-content endpoints (HTML, summary, mobile-HTML, title metadata)
    and Parsoid transform endpoints (wikitext ↔ HTML, lint). Capped at ~200
    req/s; a unique User-Agent or Api-User-Agent header is required. Content
    is CC BY-SA 4.0.
  version: '1.0.0'
  termsOfService: https://foundation.wikimedia.org/wiki/Terms_of_Use
  contact:
    name: Wikimedia Foundation
    url: https://en.wiktionary.org/api/rest_v1/
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
  - url: https://en.wiktionary.org/api/rest_v1
    description: English Wiktionary REST API
security:
  - {}
tags:
  - name: Definition
    description: Wiktionary-specific structured multilingual definition endpoint
  - name: Page Content
    description: Page HTML, summary, title metadata, and mobile-optimised HTML
  - name: Transform
    description: Parsoid wikitext ↔ HTML transforms and lint
paths:
  /page/definition/{term}:
    get:
      operationId: getDefinition
      summary: Wiktionary Get Definition
      description: >-
        Return a multilingual structured definition for a term, broken down by
        source language code (en, fr, de, …) and then by part of speech.
        Wiktionary-specific endpoint built on top of Parsoid parsing.
      tags:
        - Definition
      parameters:
        - name: term
          in: path
          required: true
          description: The dictionary term (URL-encoded; case-sensitive on Wiktionary).
          schema:
            type: string
          example: hello
        - name: redirect
          in: query
          required: false
          description: Whether to follow page redirects (defaults to true).
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Multilingual definition response keyed by language code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefinitionResponse'
        '301':
          description: Permanent redirect to the canonical term page.
        '302':
          description: Temporary redirect to a different term page.
        '404':
          description: Term not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '501':
          description: Unsupported language for structured definitions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /page/summary/{title}:
    get:
      operationId: getPageSummary
      summary: Wiktionary Get Page Summary
      description: >-
        Return a short structured summary of a Wiktionary page, including the
        leading extract and metadata. Useful for previews and tooltips.
      tags:
        - Page Content
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title.
          schema:
            type: string
          example: hello
        - name: redirect
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Whether to follow redirects.
      responses:
        '200':
          description: Page summary response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageSummary'
        '404':
          description: Page not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /page/html/{title}:
    get:
      operationId: getPageHtml
      summary: Wiktionary Get Page HTML
      description: >-
        Return the latest Parsoid HTML for a page title. Suitable for direct
        rendering in client applications.
      tags:
        - Page Content
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title.
          schema:
            type: string
          example: hello
        - name: redirect
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Whether to follow redirects.
        - name: stash
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to stash the result for later transform calls.
        - name: Accept-Language
          in: header
          required: false
          schema:
            type: string
          description: BCP-47 language tag for content-language negotiation.
      responses:
        '200':
          description: Parsoid HTML.
          content:
            text/html:
              schema:
                type: string
                description: Parsoid HTML for the requested page.
        '404':
          description: Page not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /page/title/{title}:
    get:
      operationId: getPageTitle
      summary: Wiktionary Get Page Title Metadata
      description: >-
        Return revision metadata for a page title — latest revision id,
        timestamp, comment, and user.
      tags:
        - Page Content
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title.
          schema:
            type: string
          example: hello
      responses:
        '200':
          description: Revision metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevisionMetadata'
        '404':
          description: Page not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /page/mobile-html/{title}:
    get:
      operationId: getPageMobileHtml
      summary: Wiktionary Get Page Mobile HTML
      description: >-
        Return mobile-optimised HTML for a page (lazy-loadable images, collapsed
        tables, theme support). Experimental stability.
      tags:
        - Page Content
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title.
          schema:
            type: string
          example: hello
        - name: redirect
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Whether to follow redirects.
      responses:
        '200':
          description: Mobile-optimised HTML.
          content:
            text/html:
              schema:
                type: string
                description: Mobile HTML.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /transform/wikitext/to/html/{title}:
    post:
      operationId: transformWikitextToHtml
      summary: Wiktionary Transform Wikitext to HTML
      description: >-
        Convert supplied wikitext to Parsoid HTML in the context of a page
        title. Rate-limited to 25 req/s (5 req/s with stash=true).
      tags:
        - Transform
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title context.
          schema:
            type: string
          example: hello
      requestBody:
        required: true
        description: Wikitext payload to transform.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WikitextTransformRequest'
      responses:
        '200':
          description: Parsoid HTML.
          content:
            text/html:
              schema:
                type: string
                description: Parsoid HTML body.
        '403':
          description: Access restricted.
        '404':
          description: Page not found.
        '410':
          description: Page has been deleted.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /transform/html/to/wikitext/{title}/{revision}:
    post:
      operationId: transformHtmlToWikitext
      summary: Wiktionary Transform HTML to Wikitext
      description: >-
        Convert supplied Parsoid HTML back to wikitext for a given page and
        revision. Requires an If-Match ETag header. Rate-limited to 25 req/s.
      tags:
        - Transform
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title.
          schema:
            type: string
          example: hello
        - name: revision
          in: path
          required: true
          description: Revision id to anchor the round-trip against.
          schema:
            type: string
          example: '12345'
        - name: If-Match
          in: header
          required: true
          description: ETag from the corresponding /page/html call.
          schema:
            type: string
      requestBody:
        required: true
        description: HTML payload to transform back to wikitext.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HtmlTransformRequest'
      responses:
        '200':
          description: Wikitext body.
          content:
            text/plain:
              schema:
                type: string
                description: Wikitext.
        '403':
          description: Access restricted.
        '404':
          description: Page not found.
        '410':
          description: Page has been deleted.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /transform/wikitext/to/lint/{title}:
    post:
      operationId: transformWikitextToLint
      summary: Wiktionary Transform Wikitext to Lint
      description: >-
        Lint supplied wikitext and return a list of structural and semantic
        issues. Experimental stability.
      tags:
        - Transform
      parameters:
        - name: title
          in: path
          required: true
          description: URL-encoded page title context.
          schema:
            type: string
          example: hello
      requestBody:
        required: true
        description: Wikitext payload to lint.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WikitextTransformRequest'
      responses:
        '200':
          description: Lint errors found in the wikitext.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LintError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DefinitionResponse:
      title: DefinitionResponse
      description: >-
        Multilingual structured definitions keyed by ISO language code. Each
        value is a list of language-grouped entries describing the term in
        that language.
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/LanguageEntry'
      example:
        en:
          - partOfSpeech: Interjection
            language: English
            definitions:
              - definition: A standard greeting.
                examples: ['Hello, world!']
                parsedExamples: []
    LanguageEntry:
      title: LanguageEntry
      description: One language's worth of definitions for the term.
      type: object
      required: [partOfSpeech, language, definitions]
      properties:
        partOfSpeech:
          type: string
          description: Grammatical part of speech for this entry.
          example: Interjection
        language:
          type: string
          description: Human-readable language name.
          example: English
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/DefinitionEntry'
    DefinitionEntry:
      title: DefinitionEntry
      type: object
      required: [definition]
      properties:
        definition:
          type: string
          description: HTML/wikitext definition body for one sense.
          example: A standard greeting.
        examples:
          type: array
          description: Raw usage example strings.
          items:
            type: string
          example: ['Hello, world!']
        parsedExamples:
          type: array
          description: Structured usage examples (HTML or translation pairs).
          items:
            type: object
            additionalProperties: true
    PageSummary:
      title: PageSummary
      description: Short structured summary of a page.
      type: object
      properties:
        type:
          type: string
          example: standard
        title:
          type: string
          example: hello
        displaytitle:
          type: string
          example: hello
        pageid:
          type: integer
          example: 12345
        extract:
          type: string
          description: Plain-text extract.
          example: A standard greeting; an expression of puzzlement.
        extract_html:
          type: string
          description: HTML extract.
          example: '<p>A standard greeting.</p>'
        content_urls:
          $ref: '#/components/schemas/ContentUrls'
        timestamp:
          type: string
          format: date-time
          example: '2025-03-15T14:30:00Z'
    ContentUrls:
      title: ContentUrls
      type: object
      properties:
        desktop:
          type: object
          properties:
            page:
              type: string
              format: uri
              example: https://en.wiktionary.org/wiki/hello
        mobile:
          type: object
          properties:
            page:
              type: string
              format: uri
              example: https://en.m.wiktionary.org/wiki/hello
    RevisionMetadata:
      title: RevisionMetadata
      description: Metadata about the latest revision of a page.
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RevisionItem'
    RevisionItem:
      title: RevisionItem
      type: object
      properties:
        title:
          type: string
          example: hello
        page_id:
          type: integer
          example: 12345
        rev:
          type: integer
          description: Revision id.
          example: 7654321
        tid:
          type: string
          example: 1c2d3e4f-aaaa-bbbb-cccc-ddddeeeeffff
        namespace:
          type: integer
          example: 0
        user_id:
          type: integer
          example: 1
        user_text:
          type: string
          example: ExampleEditor
        timestamp:
          type: string
          format: date-time
          example: '2025-03-15T14:30:00Z'
        comment:
          type: string
          example: typo fix
        tags:
          type: array
          items:
            type: string
          example: []
        restrictions:
          type: array
          items:
            type: string
          example: []
        page_language:
          type: string
          example: en
    WikitextTransformRequest:
      title: WikitextTransformRequest
      type: object
      required: [wikitext]
      properties:
        wikitext:
          type: string
          description: Wikitext content to transform.
          example: "==English==\n===Interjection===\n# A standard greeting."
        body_only:
          type: boolean
          description: If true, only return the body fragment instead of a full HTML document.
          example: true
        stash:
          type: boolean
          description: If true, server-side stash for later /transform calls.
          example: false
    HtmlTransformRequest:
      title: HtmlTransformRequest
      type: object
      required: [html]
      properties:
        html:
          type: string
          description: Parsoid HTML to convert back to wikitext.
          example: '<section><h2>English</h2><p>A standard greeting.</p></section>'
        scrub_wikitext:
          type: boolean
          description: Whether to clean up the resulting wikitext.
          example: true
    LintError:
      title: LintError
      description: One Parsoid lint error found in supplied wikitext.
      type: object
      properties:
        type:
          type: string
          description: Lint error category.
          example: missing-end-tag
        dsr:
          type: array
          description: Source range [start, end, openWidth, closeWidth].
          items:
            type: integer
          example: [0, 12, 0, 0]
        templateInfo:
          type: object
          additionalProperties: true
          description: If the error originates inside a template, info about it.
        params:
          type: object
          additionalProperties: true
          description: Error-specific parameters.
    ProblemDetails:
      title: ProblemDetails
      description: RFC 7807 problem-details error envelope.
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://mediawiki.org/wiki/HyperSwitch/errors/not_found
        title:
          type: string
          example: Not found.
        method:
          type: string
          example: get
        detail:
          type: string
          example: Page or revision not found.
        uri:
          type: string
          example: /en.wiktionary.org/v1/page/definition/nonexistentword