openapi: 3.0.3
info:
  title: Wordnik Account Words API
  description: 'Wordnik is the world''s biggest online English dictionary. The Wordnik API exposes

    word definitions (from five dictionaries), etymologies, real example sentences from

    millions of sources, audio pronunciations, related-word relationships, frequency data,

    hyphenation, phrases, scrabble scores, random words, reverse-dictionary lookup,

    word-of-the-day, and user word lists.'
  version: '4.0'
  contact:
    name: Wordnik API Team
    email: apiteam@wordnik.com
    url: https://developer.wordnik.com
  termsOfService: https://www.wordnik.com/about
  license:
    name: Wordnik Terms of Service
    url: https://www.wordnik.com/about
  x-providerName: wordnik.com
  x-apisguru-categories:
  - text
  x-logo:
    url: https://wordnik.com/img/logo-wordnik-home.png
  x-last-validated: '2026-05-29'
  x-origin:
  - format: openapi
    url: https://developer.wordnik.com/api-docs/swagger.json
    version: '2.0'
servers:
- url: https://api.wordnik.com/v4
  description: Wordnik v4 production API
security:
- api_key: []
tags:
- name: Words
  description: Cross-word operations (random words, reverse-dictionary search, full-text search, word-of-the-day).
paths:
  /words.json/randomWord:
    get:
      operationId: getRandomWord
      summary: Return A Single Random Word
      description: Returns a single random WordObject filtered by part of speech, length, dictionary count, and corpus count.
      tags:
      - Words
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: hasDictionaryDef
        in: query
        required: false
        description: Only return words with dictionary definitions.
        schema:
          type: string
          default: 'true'
      - name: includePartOfSpeech
        in: query
        required: false
        description: CSV part-of-speech values to include.
        schema:
          type: string
      - name: excludePartOfSpeech
        in: query
        required: false
        description: CSV part-of-speech values to exclude.
        schema:
          type: string
      - name: minCorpusCount
        in: query
        required: false
        description: Minimum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: 0
      - name: maxCorpusCount
        in: query
        required: false
        description: Maximum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minDictionaryCount
        in: query
        required: false
        description: Minimum dictionary count.
        schema:
          type: integer
          format: int32
          default: 1
      - name: maxDictionaryCount
        in: query
        required: false
        description: Maximum dictionary count.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minLength
        in: query
        required: false
        description: Minimum word length.
        schema:
          type: integer
          format: int32
          default: 5
      - name: maxLength
        in: query
        required: false
        description: Maximum word length.
        schema:
          type: integer
          format: int32
          default: -1
      responses:
        '200':
          description: A single random WordObject.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordObject'
  /words.json/randomWords:
    get:
      operationId: getRandomWords
      summary: Return An Array Of Random Words
      description: Returns an array of random WordObjects filtered by part of speech, length, dictionary count, and corpus count.
      tags:
      - Words
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: hasDictionaryDef
        in: query
        required: false
        description: Only return words with dictionary definitions.
        schema:
          type: string
          default: 'true'
      - name: includePartOfSpeech
        in: query
        required: false
        description: CSV part-of-speech values to include.
        schema:
          type: string
      - name: excludePartOfSpeech
        in: query
        required: false
        description: CSV part-of-speech values to exclude.
        schema:
          type: string
      - name: minCorpusCount
        in: query
        required: false
        description: Minimum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: 0
      - name: maxCorpusCount
        in: query
        required: false
        description: Maximum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minDictionaryCount
        in: query
        required: false
        description: Minimum dictionary count.
        schema:
          type: integer
          format: int32
          default: 1
      - name: maxDictionaryCount
        in: query
        required: false
        description: Maximum dictionary count.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minLength
        in: query
        required: false
        description: Minimum word length.
        schema:
          type: integer
          format: int32
          default: 5
      - name: maxLength
        in: query
        required: false
        description: Maximum word length.
        schema:
          type: integer
          format: int32
          default: -1
      - name: sortBy
        in: query
        required: false
        description: Attribute to sort by.
        schema:
          type: string
          enum:
          - alpha
          - count
      - name: sortOrder
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Array of random WordObject entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WordObject'
  /words.json/reverseDictionary:
    get:
      operationId: reverseDictionary
      summary: Reverse Dictionary Search
      description: Returns the words that best match a natural-language query string.
      tags:
      - Words
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: query
        in: query
        required: true
        description: Search term.
        schema:
          type: string
          example: feeling of happiness
      - name: findSenseForWord
        in: query
        required: false
        description: Restricts words and finds closest sense.
        schema:
          type: string
      - name: includeSourceDictionaries
        in: query
        required: false
        description: Only include these comma-delimited source dictionaries.
        schema:
          type: string
          enum:
          - ahd-5
          - century
          - cmu
          - macmillan
          - wiktionary
          - webster
          - wordnet
      - name: excludeSourceDictionaries
        in: query
        required: false
        description: Exclude these comma-delimited source dictionaries.
        schema:
          type: string
          enum:
          - ahd-5
          - century
          - cmu
          - macmillan
          - wiktionary
          - webster
          - wordnet
      - name: includePartOfSpeech
        in: query
        required: false
        description: Only include these comma-delimited parts of speech.
        schema:
          type: string
      - name: excludePartOfSpeech
        in: query
        required: false
        description: Exclude these comma-delimited parts of speech.
        schema:
          type: string
      - name: minCorpusCount
        in: query
        required: false
        description: Minimum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: 5
      - name: maxCorpusCount
        in: query
        required: false
        description: Maximum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minLength
        in: query
        required: false
        description: Minimum word length.
        schema:
          type: integer
          format: int32
          default: 1
      - name: maxLength
        in: query
        required: false
        description: Maximum word length.
        schema:
          type: integer
          format: int32
          default: -1
      - name: expandTerms
        in: query
        required: false
        description: Expand terms.
        schema:
          type: string
      - name: includeTags
        in: query
        required: false
        description: Return a closed set of XML tags in response.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
      - name: sortBy
        in: query
        required: false
        description: Attribute to sort by.
        schema:
          type: string
          enum:
          - alpha
          - count
      - name: sortOrder
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: skip
        in: query
        required: false
        description: Results to skip.
        schema:
          type: string
          default: '0'
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: DefinitionSearchResults payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefinitionSearchResults'
  /words.json/search/{query}:
    get:
      operationId: searchWords
      summary: Search Words
      description: Searches for words matching the supplied query (literal or regular expression).
      tags:
      - Words
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: query
        in: path
        required: true
        description: Search query.
        schema:
          type: string
          example: ser
      - name: allowRegex
        in: query
        required: false
        description: Search term is a regular expression.
        schema:
          type: string
          default: 'false'
      - name: caseSensitive
        in: query
        required: false
        description: Search case sensitive.
        schema:
          type: string
          default: 'true'
      - name: includePartOfSpeech
        in: query
        required: false
        description: Only include these comma-delimited parts of speech.
        schema:
          type: string
      - name: excludePartOfSpeech
        in: query
        required: false
        description: Exclude these comma-delimited parts of speech.
        schema:
          type: string
      - name: minCorpusCount
        in: query
        required: false
        description: Minimum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: 5
      - name: maxCorpusCount
        in: query
        required: false
        description: Maximum corpus frequency for terms.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minDictionaryCount
        in: query
        required: false
        description: Minimum number of dictionary entries for words returned.
        schema:
          type: integer
          format: int32
          default: 1
      - name: maxDictionaryCount
        in: query
        required: false
        description: Maximum dictionary definition count.
        schema:
          type: integer
          format: int32
          default: -1
      - name: minLength
        in: query
        required: false
        description: Minimum word length.
        schema:
          type: integer
          format: int32
          default: 1
      - name: maxLength
        in: query
        required: false
        description: Maximum word length.
        schema:
          type: integer
          format: int32
          default: -1
      - name: skip
        in: query
        required: false
        description: Results to skip.
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: WordSearchResults payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordSearchResults'
  /words.json/wordOfTheDay:
    get:
      operationId: getWordOfTheDay
      summary: Return The Word Of The Day
      description: Returns the Word of the Day, optionally for a specific date.
      tags:
      - Words
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: date
        in: query
        required: false
        description: Fetches by date in yyyy-MM-dd.
        schema:
          type: string
          example: '2026-05-29'
      responses:
        '200':
          description: A single WordOfTheDay payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordOfTheDay'
components:
  schemas:
    DefinitionSearchResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimpleDefinition'
        totalResults:
          type: integer
          format: int32
    WordSearchResults:
      type: object
      properties:
        searchResults:
          type: array
          items:
            $ref: '#/components/schemas/WordSearchResult'
        totalResults:
          type: integer
          format: int32
    ContentProvider:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
    WordOfTheDay:
      type: object
      required:
      - id
      properties:
        category:
          type: string
        contentProvider:
          $ref: '#/components/schemas/ContentProvider'
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/SimpleDefinition'
        examples:
          type: array
          items:
            $ref: '#/components/schemas/SimpleExample'
        htmlExtra:
          type: string
        id:
          type: integer
          format: int64
        note:
          type: string
        parentId:
          type: string
        publishDate:
          type: string
          format: date
        word:
          type: string
    WordSearchResult:
      type: object
      properties:
        count:
          type: integer
          format: int64
        lexicality:
          type: number
          format: double
        word:
          type: string
    SimpleExample:
      type: object
      properties:
        id:
          type: integer
          format: int64
        text:
          type: string
        title:
          type: string
        url:
          type: string
          format: uri
    WordObject:
      type: object
      required:
      - id
      properties:
        canonicalForm:
          type: string
        id:
          type: integer
          format: int64
        originalWord:
          type: string
        suggestions:
          type: array
          items:
            type: string
        vulgar:
          type: string
        word:
          type: string
    SimpleDefinition:
      type: object
      properties:
        note:
          type: string
        partOfSpeech:
          type: string
        source:
          type: string
        text:
          type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query
      description: Wordnik issues per-account API keys; pass via the `api_key` query parameter on every request.
    auth_token:
      type: apiKey
      name: auth_token
      in: header
      description: User auth token returned by `/account.json/authenticate/{username}`; required for user-scoped account and word-list operations.
externalDocs:
  description: Wordnik Developer Documentation
  url: https://developer.wordnik.com