openapi: 3.0.3
info:
  title: Wordnik
  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"
externalDocs:
  description: Wordnik Developer Documentation
  url: https://developer.wordnik.com
servers:
  - url: https://api.wordnik.com/v4
    description: Wordnik v4 production API
security:
  - api_key: []
tags:
  - name: Word
    description: Operations on a single English word (definitions, etymologies, examples, pronunciations, related words, frequency, hyphenation, phrases, scrabble score, audio).
  - name: Words
    description: Cross-word operations (random words, reverse-dictionary search, full-text search, word-of-the-day).
  - name: Word List
    description: Read and write operations on an individual user word list.
  - name: Word Lists
    description: Create new user word lists.
  - name: Account
    description: API-key status and user authentication operations.
paths:
  "/word.json/{word}/audio":
    get:
      operationId: getAudio
      summary: Fetch Audio Metadata For A Word
      description: |-
        The metadata includes a time-expiring fileUrl which allows reading the audio file
        directly from the API. Currently only audio pronunciations from the American Heritage
        Dictionary in mp3 format are supported.
      tags: [Word]
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
        - name: word
          in: path
          required: true
          description: Word to get audio for.
          schema: { type: string, example: "cat" }
        - name: useCanonical
          in: query
          required: false
          description: Return the canonical form of the word (e.g. 'cats' -> 'cat').
          schema: { type: string, enum: ["true", "false"], default: "false" }
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return.
          schema: { type: integer, format: int32, default: 50 }
      responses:
        "200":
          description: Array of AudioFile metadata entries.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/AudioFile" }
  "/word.json/{word}/definitions":
    get:
      operationId: getDefinitions
      summary: Return Definitions For A Word
      description: Returns definitions for the given word from one or more source dictionaries.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to return definitions for., schema: { type: string, example: "serendipity" } }
        - { name: limit, in: query, required: false, description: Maximum number of results to return., schema: { type: integer, format: int32, default: 200 } }
        - name: partOfSpeech
          in: query
          required: false
          description: CSV list of part-of-speech types.
          schema:
            type: string
            enum: [noun, adjective, verb, adverb, interjection, pronoun, preposition, abbreviation, affix, article, auxiliary-verb, conjunction, definite-article, family-name, given-name, idiom, imperative, noun-plural, noun-posessive, past-participle, phrasal-prefix, proper-noun, proper-noun-plural, proper-noun-posessive, suffix, verb-intransitive, verb-transitive]
        - { name: includeRelated, in: query, required: false, description: Return related words with definitions., schema: { type: string, default: "false" } }
        - name: sourceDictionaries
          in: query
          required: false
          style: form
          explode: false
          description: Source dictionary to return definitions from. If 'all' is received, results are returned from all sources. If multiple values are received (e.g. 'century,wiktionary'), results are returned from the first specified dictionary that has definitions. If left blank, results are returned from the first dictionary that has definitions. By default, dictionaries are searched in this order:- ahd-5, wiktionary, webster, century, wordnet.
          schema:
            type: array
            items: { type: string, enum: [all, ahd-5, century, wiktionary, webster, wordnet] }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { name: includeTags, in: query, required: false, description: Return a closed set of XML tags in response., schema: { type: string, enum: ["true", "false"], default: "false" } }
      responses:
        "200":
          description: Array of Definition objects.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/Definition" } }
  "/word.json/{word}/etymologies":
    get:
      operationId: getEtymologies
      summary: Fetch Etymology Data For A Word
      description: Returns the etymology entries for a word, typically as XML-tagged strings.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to return etymologies for., schema: { type: string, example: "serendipity" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
      responses:
        "200":
          description: Array of etymology strings.
          content:
            application/json:
              schema: { type: array, items: { type: string } }
  "/word.json/{word}/examples":
    get:
      operationId: getExamples
      summary: Return Examples For A Word
      description: Returns real-world example sentences for a word.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to return examples for., schema: { type: string, example: "serendipity" } }
        - { name: includeDuplicates, in: query, required: false, description: Show duplicate examples from different sources., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { 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: 5 } }
      responses:
        "200":
          description: ExampleSearchResults payload containing examples and facets.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExampleSearchResults" }
  "/word.json/{word}/frequency":
    get:
      operationId: getWordFrequency
      summary: Return Word Usage Over Time
      description: Returns a frequency summary describing how often a word has been used per year.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to return., schema: { type: string, example: "serendipity" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { name: startYear, in: query, required: false, description: Starting year., schema: { type: integer, format: int32, default: 1800 } }
        - { name: endYear, in: query, required: false, description: Ending year., schema: { type: integer, format: int32, default: 2012 } }
      responses:
        "200":
          description: Frequency summary for the word.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FrequencySummary" }
  "/word.json/{word}/hyphenation":
    get:
      operationId: getHyphenation
      summary: Return Syllable Information For A Word
      description: Returns the syllabification (hyphenation) data for a word.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to get syllables for., schema: { type: string, example: "serendipity" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { name: sourceDictionary, in: query, required: false, description: "Get from a single dictionary. Valid options: ahd-5, century, wiktionary, webster, and wordnet.", schema: { type: string, enum: [ahd-5, century, wiktionary, webster, wordnet] } }
        - { name: limit, in: query, required: false, description: Maximum number of results to return., schema: { type: integer, format: int32, default: 50 } }
      responses:
        "200":
          description: Array of Syllable objects.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/Syllable" } }
  "/word.json/{word}/phrases":
    get:
      operationId: getPhrases
      summary: Fetch Bi-gram Phrases For A Word
      description: Returns the top bi-gram phrases that include the given word.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to fetch phrases for., schema: { type: string, example: "kick" } }
        - { name: limit, in: query, required: false, description: Maximum number of results to return., schema: { type: integer, format: int32, default: 5 } }
        - { name: wlmi, in: query, required: false, description: Minimum WLMI for the phrase., schema: { type: integer, format: int32, default: 0 } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
      responses:
        "200":
          description: Array of Bigram phrase entries.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/Bigram" } }
  "/word.json/{word}/pronunciations":
    get:
      operationId: getTextPronunciations
      summary: Return Text Pronunciations For A Word
      description: Returns one or more text pronunciations for a given word in any of the supported formats.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to get pronunciations for., schema: { type: string, example: "serendipity" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - { name: sourceDictionary, in: query, required: false, description: Get from a single dictionary., schema: { type: string, enum: [ahd-5, century, cmu, macmillan, wiktionary, webster, wordnet] } }
        - { name: typeFormat, in: query, required: false, description: Text pronunciation type., schema: { type: string, enum: [ahd-5, arpabet, gcide-diacritical, IPA] } }
        - { name: limit, in: query, required: false, description: Maximum number of results to return., schema: { type: integer, format: int32, default: 50 } }
      responses:
        "200":
          description: Array of TextPron objects.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/TextPron" } }
  "/word.json/{word}/relatedWords":
    get:
      operationId: getRelatedWords
      summary: Return Related Words From The Word Graph
      description: Given a word as a string, returns relationships from the Wordnik Word Graph (synonyms, antonyms, hypernyms, hyponyms, etc.).
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to fetch relationships for., schema: { type: string, example: "happy" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
        - name: relationshipTypes
          in: query
          required: false
          description: Limits the total results per type of relationship type.
          schema:
            type: string
            enum: [synonym, antonym, variant, equivalent, cross-reference, related-word, rhyme, form, etymologically-related-term, hypernym, hyponym, inflected-form, primary, same-context, verb-form, verb-stem, has_topic]
        - { name: limitPerRelationshipType, in: query, required: false, description: Restrict to the supplied relationship types., schema: { type: integer, format: int32, default: 10 } }
      responses:
        "200":
          description: Array of Related word-group objects.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/Related" } }
  "/word.json/{word}/scrabbleScore":
    get:
      operationId: getScrabbleScore
      summary: Return The Scrabble Score For A Word
      description: Returns the scrabble score for a given word.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to get scrabble score for., schema: { type: string, example: "quiz" } }
      responses:
        "200":
          description: ScrabbleScoreResult containing a single value.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ScrabbleScoreResult" }
  "/word.json/{word}/topExample":
    get:
      operationId: getTopExample
      summary: Return A Top Example For A Word
      description: Returns a single top example sentence for a given word.
      tags: [Word]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      parameters:
        - { name: word, in: path, required: true, description: Word to fetch examples for., schema: { type: string, example: "serendipity" } }
        - { name: useCanonical, in: query, required: false, description: Return the canonical form of the word., schema: { type: string, enum: ["true", "false"], default: "false" } }
      responses:
        "200":
          description: A single Example payload.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Example" }
  "/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" }
  "/account.json/apiTokenStatus":
    get:
      operationId: getApiTokenStatus
      summary: Return API Token Status
      description: Returns the current quota, total requests, and remaining-call status for the supplied API key. Endpoint surface verified from the Wordnik official client SDK (wordnik-clients/java AccountApi).
      tags: [Account]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: api_key, in: header, required: false, description: Wordnik API key (when not using the query parameter)., schema: { type: string } }
      responses:
        "200":
          description: ApiTokenStatus payload describing the supplied key.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiTokenStatus" }
  "/account.json/authenticate/{username}":
    get:
      operationId: authenticate
      summary: Authenticate A User
      description: Authenticates a Wordnik user using the supplied password and returns an auth token for subsequent user-scoped operations.
      tags: [Account]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: username, in: path, required: true, description: A confirmed Wordnik username., schema: { type: string } }
        - { name: password, in: query, required: true, description: The user's password., schema: { type: string, format: password } }
      responses:
        "200":
          description: AuthenticationToken payload.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AuthenticationToken" }
    post:
      operationId: authenticatePost
      summary: Authenticate A User (POST Body)
      description: Same as the GET form, but the password is sent in the request body to avoid logging the credential in URL query strings.
      tags: [Account]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: username, in: path, required: true, description: A confirmed Wordnik username., schema: { type: string } }
      requestBody:
        required: true
        content:
          text/plain:
            schema: { type: string, description: The user's password as a plain string. }
      responses:
        "200":
          description: AuthenticationToken payload.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AuthenticationToken" }
  "/account.json/user":
    get:
      operationId: getLoggedInUser
      summary: Return The Currently Authenticated User
      description: Returns the User profile associated with the supplied auth token.
      tags: [Account]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: auth_token, in: header, required: true, description: A valid user auth token obtained via /account.json/authenticate., schema: { type: string } }
      responses:
        "200":
          description: User profile payload.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
  "/account.json/wordLists":
    get:
      operationId: getWordListsForLoggedInUser
      summary: Return The Authenticated User's Word Lists
      description: Returns all word lists owned by the currently authenticated user.
      tags: [Account]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
        - { 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 lists to return., schema: { type: integer, format: int32, default: 50 } }
      responses:
        "200":
          description: Array of WordList objects owned by the user.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/WordList" } }
  "/wordLists.json":
    post:
      operationId: createWordList
      summary: Create A New Word List
      description: Creates a new word list owned by the authenticated user. Endpoint surface verified from the Wordnik official client SDK (wordnik-clients/java WordListsApi).
      tags: [Word Lists]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WordList" }
      responses:
        "200":
          description: The created WordList.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WordList" }
  "/wordList.json/{permalink}":
    get:
      operationId: getWordListByPermalink
      summary: Return A Word List By Permalink
      description: Returns the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      responses:
        "200":
          description: The WordList payload.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WordList" }
    put:
      operationId: updateWordList
      summary: Update A Word List
      description: Updates the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WordList" }
      responses:
        "204": { description: WordList updated. }
    delete:
      operationId: deleteWordList
      summary: Delete A Word List
      description: Deletes the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      responses:
        "204": { description: WordList deleted. }
  "/wordList.json/{permalink}/words":
    get:
      operationId: getWordListWords
      summary: Return Words In A Word List
      description: Returns the words contained in the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
        - { name: sortBy, in: query, required: false, description: Attribute to sort by., schema: { type: string, enum: [alpha, createDate] } }
        - { 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: integer, format: int32, default: 0 } }
        - { name: limit, in: query, required: false, description: Maximum number of results to return., schema: { type: integer, format: int32, default: 100 } }
      responses:
        "200":
          description: Array of WordListWord entries.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/WordListWord" } }
    post:
      operationId: addWordsToWordList
      summary: Add Words To A Word List
      description: Adds one or more words to the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: { $ref: "#/components/schemas/StringValue" }
      responses:
        "204": { description: Words added to the WordList. }
  "/wordList.json/{permalink}/deleteWords":
    post:
      operationId: deleteWordsFromWordList
      summary: Delete Words From A Word List
      description: Removes one or more words from the WordList identified by the supplied permalink.
      tags: [Word List]
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
      x-schema-source: sdk
      x-sdk-repo: https://github.com/wordnik/wordnik-clients
      parameters:
        - { name: permalink, in: path, required: true, description: Permalink of the word list., schema: { type: string } }
        - { name: auth_token, in: header, required: true, description: A valid user auth token., schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: { $ref: "#/components/schemas/StringValue" }
      responses:
        "204": { description: Words removed from the WordList. }
components:
  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.
  schemas:
    ApiTokenStatus:
      type: object
      properties:
        expiresInMillis: { type: integer, format: int64 }
        remainingCalls: { type: integer, format: int64 }
        resetsInMillis: { type: integer, format: int64 }
        token: { type: string }
        totalRequests: { type: integer, format: int64 }
        valid: { type: boolean }
    AudioFile:
      type: object
      required: [id]
      properties:
        attributionText: { type: string }
        attributionUrl: { type: string }
        audioType: { type: string, example: "pronunciation" }
        commentCount: { type: integer, format: int32 }
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
        description: { type: string }
        duration: { type: number, format: double }
        fileUrl: { type: string, format: uri }
        id: { type: integer, format: int64 }
        voteAverage: { type: number, format: float }
        voteCount: { type: integer }
        voteWeightedAverage: { type: number, format: float }
        word: { type: string }
    AudioType:
      type: object
      properties:
        id: { type: integer, format: int32 }
        name: { type: string }
    AuthenticationToken:
      type: object
      properties:
        token: { type: string }
        userId: { type: integer, format: int64 }
        userSignature: { type: string }
    Bigram:
      type: object
      properties:
        count: { type: integer, format: int64 }
        gram1: { type: string }
        gram2: { type: string }
        mi: { type: number, format: double, description: "Mutual information score" }
        wlmi: { type: number, format: double, description: "Word-list mutual information score" }
    Category:
      type: object
      required: [id]
      properties:
        id: { type: integer, format: int64 }
        name: { type: string }
    Citation:
      type: object
      properties:
        cite: { type: string }
        source: { type: string }
    ContentProvider:
      type: object
      properties:
        id: { type: integer, format: int32 }
        name: { type: string }
    Definition:
      type: object
      properties:
        attributionText: { type: string }
        attributionUrl: { type: string }
        citations:
          type: array
          items: { $ref: "#/components/schemas/Citation" }
        exampleUses:
          type: array
          items: { $ref: "#/components/schemas/ExampleUsage" }
        extendedText: { type: string }
        labels:
          type: array
          items: { $ref: "#/components/schemas/Label" }
        notes:
          type: array
          items: { $ref: "#/components/schemas/Note" }
        partOfSpeech: { type: string }
        relatedWords:
          type: array
          items: { $ref: "#/components/schemas/Related" }
        score: { type: number, format: float }
        seqString: { type: string }
        sequence: { type: string }
        sourceDictionary: { type: string, example: "ahd-5" }
        text: { type: string }
        textProns:
          type: array
          items: { $ref: "#/components/schemas/TextPron" }
        word: { type: string }
    DefinitionSearchResults:
      type: object
      properties:
        results:
          type: array
          items: { $ref: "#/components/schemas/SimpleDefinition" }
        totalResults: { type: integer, format: int32 }
    Example:
      type: object
      properties:
        documentId: { type: integer, format: int64 }
        exampleId: { type: integer, format: int64 }
        id: { type: integer, format: int64 }
        provider: { $ref: "#/components/schemas/ContentProvider" }
        rating: { type: number, format: float }
        score: { $ref: "#/components/schemas/ScoredWord" }
        sentence: { $ref: "#/components/schemas/Sentence" }
        text: { type: string }
        title: { type: string }
        url: { type: string, format: uri }
        word: { type: string }
        year: { type: integer }
    ExampleSearchResults:
      type: object
      properties:
        examples:
          type: array
          items: { $ref: "#/components/schemas/Example" }
        facets:
          type: array
          items: { $ref: "#/components/schemas/Facet" }
    ExampleUsage:
      type: object
      properties:
        text: { type: string }
    Facet:
      type: object
      properties:
        facetValues:
          type: array
          items: { $ref: "#/components/schemas/FacetValue" }
        name: { type: string }
    FacetValue:
      type: object
      properties:
        count: { type: integer, format: int64 }
        value: { type: string }
    Frequency:
      type: object
      properties:
        count: { type: integer, format: int64 }
        year: { type: integer, format: int32 }
    FrequencySummary:
      type: object
      properties:
        frequency:
          type: array
          items: { $ref: "#/components/schemas/Frequency" }
        frequencyString: { type: string }
        totalCount: { type: integer, format: int64 }
        unknownYearCount: { type: integer, format: int32 }
        word: { type: string }
    Label:
      type: object
      properties:
        text: { type: string }
        type: { type: string }
    Note:
      type: object
      properties:
        appliesTo:
          type: array
          items: { type: string }
        noteType: { type: string }
        pos: { type: integer, format: int32 }
        value: { type: string }
    PartOfSpeech:
      type: object
      properties:
        allCategories:
          type: array
          items: { $ref: "#/components/schemas/Category" }
        roots:
          type: array
          items: { $ref: "#/components/schemas/Root" }
        storageAbbr:
          type: array
          items: { type: string }
    Related:
      type: object
      properties:
        gram: { type: string }
        label1: { type: string }
        label2: { type: string }
        label3: { type: string }
        label4: { type: string }
        relationshipType: { type: string, example: "synonym" }
        words:
          type: array
          items: { type: string }
    Root:
      type: object
      required: [id]
      properties:
        categories:
          type: array
          items: { $ref: "#/components/schemas/Category" }
        id: { type: integer, format: int64 }
        name: { type: string }
    ScrabbleScoreResult:
      type: object
      properties:
        value: { type: integer, format: int64 }
    ScoredWord:
      type: object
      properties:
        baseWordScore: { type: number, format: double }
        docTermCount: { type: integer, format: int32 }
        id: { type: integer, format: int64 }
        lemma: { type: string }
        partOfSpeech: { type: string }
        position: { type: integer, format: int32 }
        score: { type: number, format: float }
        sentenceId: { type: integer, format: int64 }
        stopword: { type: boolean }
        word: { type: string }
        wordType: { type: string }
    Sentence:
      type: object
      properties:
        display: { type: string }
        documentMetadataId: { type: integer, format: int64 }
        hasScoredWords: { type: boolean }
        id: { type: integer, format: int64 }
        rating: { type: integer, format: int32 }
        scoredWords:
          type: array
          items: { $ref: "#/components/schemas/ScoredWord" }
    SimpleDefinition:
      type: object
      properties:
        note: { type: string }
        partOfSpeech: { type: string }
        source: { type: string }
        text: { type: string }
    SimpleExample:
      type: object
      properties:
        id: { type: integer, format: int64 }
        text: { type: string }
        title: { type: string }
        url: { type: string, format: uri }
    StringValue:
      type: object
      properties:
        word: { type: string }
    Syllable:
      type: object
      properties:
        seq: { type: integer, format: int32 }
        text: { type: string }
        type: { type: string, enum: [stress, secondary, normal] }
    TextPron:
      type: object
      properties:
        raw: { type: string }
        rawType: { type: string }
        seq: { type: integer, format: int32 }
    User:
      type: object
      properties:
        displayName: { type: string }
        email: { type: string, format: email }
        faceBookId: { type: string }
        id: { type: integer, format: int64 }
        password: { type: string, format: password }
        status: { type: integer, format: int32 }
        userName: { type: string }
        username: { type: string }
    WordList:
      type: object
      required: [id]
      properties:
        createdAt: { type: string, format: date-time }
        description: { type: string }
        id: { type: integer, format: int64 }
        lastActivityAt: { type: string, format: date-time }
        name: { type: string }
        numberWordsInList: { type: integer, format: int64 }
        permalink: { type: string }
        type: { type: string, enum: [PUBLIC, PRIVATE] }
        updatedAt: { type: string, format: date-time }
        userId: { type: integer, format: int64 }
        username: { type: string }
    WordListWord:
      type: object
      required: [id]
      properties:
        createdAt: { type: string, format: date-time }
        id: { type: integer, format: int64 }
        numberCommentsOnWord: { type: integer, format: int64 }
        numberLists: { type: integer, format: int64 }
        userId: { type: integer, format: int64 }
        username: { type: string }
        word: { type: string }
    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 }
    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 }
    WordSearchResults:
      type: object
      properties:
        searchResults:
          type: array
          items: { $ref: "#/components/schemas/WordSearchResult" }
        totalResults: { type: integer, format: int32 }