openapi: 3.0.3
info:
  title: Wordnik Account Word 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: Word
  description: Operations on a single English word (definitions, etymologies, examples, pronunciations, related words, frequency, hyphenation, phrases, scrabble score, audio).
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'
components:
  schemas:
    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
    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'
    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
    TextPron:
      type: object
      properties:
        raw:
          type: string
        rawType:
          type: string
        seq:
          type: integer
          format: int32
    Note:
      type: object
      properties:
        appliesTo:
          type: array
          items:
            type: string
        noteType:
          type: string
        pos:
          type: integer
          format: int32
        value:
          type: string
    Citation:
      type: object
      properties:
        cite:
          type: string
        source:
          type: string
    ContentProvider:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
    ExampleUsage:
      type: object
      properties:
        text:
          type: string
    Label:
      type: object
      properties:
        text:
          type: string
        type:
          type: string
    Facet:
      type: object
      properties:
        facetValues:
          type: array
          items:
            $ref: '#/components/schemas/FacetValue'
        name:
          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
    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
    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
    Syllable:
      type: object
      properties:
        seq:
          type: integer
          format: int32
        text:
          type: string
        type:
          type: string
          enum:
          - stress
          - secondary
          - normal
    ExampleSearchResults:
      type: object
      properties:
        examples:
          type: array
          items:
            $ref: '#/components/schemas/Example'
        facets:
          type: array
          items:
            $ref: '#/components/schemas/Facet'
    FacetValue:
      type: object
      properties:
        count:
          type: integer
          format: int64
        value:
          type: string
    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
    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
  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