openapi: 3.1.0
info:
  title: Datamuse API
  description: |
    The Datamuse API is a word-finding query engine for developers. It returns lists of
    words (and optional metadata) matching a combination of semantic, phonetic, orthographic,
    and vocabulary constraints, plus context ranking hints. The API powers OneLook,
    OneLook Thesaurus, RhymeZone, Rimar.io, and CivicSearch.

    Two operations are exposed:

    * `GET /words` — find words matching a rich set of constraint and ranking parameters.
    * `GET /sug` — return autocomplete suggestions for a partially-entered string.

    The service is free for non-commercial use up to 100,000 requests per day with no
    API key required. Commercial use, higher rate limits, and custom vocabularies are
    available via a paid commercial agreement.
  version: 1.1.0
  termsOfService: https://www.datamuse.com/api/
  contact:
    name: Datamuse API Support
    url: https://www.datamuse.com/api/
  license:
    name: Datamuse Free Non-Commercial Use
    url: https://www.datamuse.com/api/
servers:
  - url: https://api.datamuse.com
    description: Datamuse production API
tags:
  - name: Words
    description: Word-finding queries combining semantic, phonetic, orthographic, and vocabulary constraints.
  - name: Suggestions
    description: Autocomplete suggestions with spelling correction and semantic fallback.
paths:
  /words:
    get:
      summary: Find Words Matching Constraints
      description: |
        Find words matching any combination of constraints. Constraints may be combined
        freely; results are ranked by relationship strength for semantic constraints,
        otherwise by frequency. Optional metadata flags add definitions, parts of speech,
        syllable counts, pronunciations, and corpus frequency to each result.
      operationId: getWords
      tags:
        - Words
      parameters:
        - $ref: '#/components/parameters/MeansLike'
        - $ref: '#/components/parameters/SoundsLike'
        - $ref: '#/components/parameters/SpelledLike'
        - $ref: '#/components/parameters/RelJja'
        - $ref: '#/components/parameters/RelJjb'
        - $ref: '#/components/parameters/RelSyn'
        - $ref: '#/components/parameters/RelTrg'
        - $ref: '#/components/parameters/RelAnt'
        - $ref: '#/components/parameters/RelSpc'
        - $ref: '#/components/parameters/RelGen'
        - $ref: '#/components/parameters/RelCom'
        - $ref: '#/components/parameters/RelPar'
        - $ref: '#/components/parameters/RelBga'
        - $ref: '#/components/parameters/RelBgb'
        - $ref: '#/components/parameters/RelRhy'
        - $ref: '#/components/parameters/RelNry'
        - $ref: '#/components/parameters/RelHom'
        - $ref: '#/components/parameters/RelCns'
        - $ref: '#/components/parameters/Vocabulary'
        - $ref: '#/components/parameters/Topics'
        - $ref: '#/components/parameters/LeftContext'
        - $ref: '#/components/parameters/RightContext'
        - $ref: '#/components/parameters/Max'
        - $ref: '#/components/parameters/Metadata'
        - $ref: '#/components/parameters/QueryEcho'
        - $ref: '#/components/parameters/Ipa'
      responses:
        '200':
          description: A ranked list of matching words.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Word'
        '400':
          description: Malformed request (unknown parameter or invalid value).
        '429':
          description: Too many requests — exceeded the 100,000 requests/day free tier limit.
  /sug:
    get:
      summary: Get Autocomplete Suggestions
      description: |
        Return intelligent autocomplete suggestions for a partially-entered search string.
        Sorted by popularity; the response may include spelling corrections or semantically
        similar terms when an exact prefix match is unavailable.
      operationId: getSuggestions
      tags:
        - Suggestions
      parameters:
        - $ref: '#/components/parameters/SuggestionPrefix'
        - $ref: '#/components/parameters/SuggestionMax'
        - $ref: '#/components/parameters/Vocabulary'
      responses:
        '200':
          description: A ranked list of suggested words.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suggestion'
        '400':
          description: Malformed request.
        '429':
          description: Too many requests — exceeded the 100,000 requests/day free tier limit.
components:
  parameters:
    MeansLike:
      name: ml
      in: query
      description: Means like — semantic constraint requiring results with meaning related to the input string (reverse-dictionary lookup).
      schema:
        type: string
      example: ringing in the ears
    SoundsLike:
      name: sl
      in: query
      description: Sounds like — phonetic constraint requiring results pronounced similarly to the input.
      schema:
        type: string
      example: jirraf
    SpelledLike:
      name: sp
      in: query
      description: Spelled like — orthographic constraint with wildcards (`*` any chars, `?` single char). URL-encode the value.
      schema:
        type: string
      example: hipp*
    RelJja:
      name: rel_jja
      in: query
      description: Popular nouns modified by the given adjective, per Google Books Ngrams.
      schema:
        type: string
    RelJjb:
      name: rel_jjb
      in: query
      description: Popular adjectives modifying the given noun, per Google Books Ngrams.
      schema:
        type: string
    RelSyn:
      name: rel_syn
      in: query
      description: Synonyms (WordNet).
      schema:
        type: string
    RelTrg:
      name: rel_trg
      in: query
      description: Triggers — words statistically associated with the query word in the same piece of text.
      schema:
        type: string
    RelAnt:
      name: rel_ant
      in: query
      description: Antonyms (WordNet).
      schema:
        type: string
    RelSpc:
      name: rel_spc
      in: query
      description: Direct hypernyms ("kind of").
      schema:
        type: string
    RelGen:
      name: rel_gen
      in: query
      description: Direct hyponyms ("more general than").
      schema:
        type: string
    RelCom:
      name: rel_com
      in: query
      description: Direct holonyms ("comprises").
      schema:
        type: string
    RelPar:
      name: rel_par
      in: query
      description: Direct meronyms ("part of").
      schema:
        type: string
    RelBga:
      name: rel_bga
      in: query
      description: Frequent followers — words that frequently appear immediately after the query word.
      schema:
        type: string
    RelBgb:
      name: rel_bgb
      in: query
      description: Frequent predecessors — words that frequently appear immediately before the query word.
      schema:
        type: string
    RelRhy:
      name: rel_rhy
      in: query
      description: Perfect rhymes.
      schema:
        type: string
    RelNry:
      name: rel_nry
      in: query
      description: Approximate (near) rhymes.
      schema:
        type: string
    RelHom:
      name: rel_hom
      in: query
      description: Homophones — words pronounced the same.
      schema:
        type: string
    RelCns:
      name: rel_cns
      in: query
      description: Consonant matches — words with the same consonant skeleton.
      schema:
        type: string
    Vocabulary:
      name: v
      in: query
      description: Vocabulary identifier. Default English (`en`, 550k terms) or `es` for Spanish (500k terms). Custom vocabularies available on request.
      schema:
        type: string
        enum:
          - en
          - es
        default: en
    Topics:
      name: topics
      in: query
      description: Up to five space- or comma-separated topic words that skew results toward the indicated document theme.
      schema:
        type: string
      example: technology computers
    LeftContext:
      name: lc
      in: query
      description: Left context — a single word appearing immediately to the left of the target word.
      schema:
        type: string
    RightContext:
      name: rc
      in: query
      description: Right context — a single word appearing immediately to the right of the target word.
      schema:
        type: string
    Max:
      name: max
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    Metadata:
      name: md
      in: query
      description: |
        Metadata flags — a string composed of single-letter codes requesting lexical
        metadata for each result:
          * `d` — definitions (and `defHeadword` for inflected forms)
          * `p` — parts of speech (n, v, adj, adv, u)
          * `s` — syllable count (`numSyllables`)
          * `r` — pronunciation (Arpabet; combine with `ipa=1` for IPA)
          * `f` — corpus frequency (per million words, Google Books Ngrams)
      schema:
        type: string
      example: dpsrf
    QueryEcho:
      name: qe
      in: query
      description: Query echo — prepend a result describing the query string from the named parameter, useful for one-shot metadata lookups.
      schema:
        type: string
    Ipa:
      name: ipa
      in: query
      description: When set to `1` and pronunciation metadata is requested, return IPA-format pronunciations instead of Arpabet.
      schema:
        type: integer
        enum:
          - 0
          - 1
    SuggestionPrefix:
      name: s
      in: query
      description: Partially-entered search string for which to return suggestions.
      required: true
      schema:
        type: string
      example: rawn
    SuggestionMax:
      name: max
      in: query
      description: Maximum number of suggestions to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 10
  schemas:
    Word:
      type: object
      description: A word returned from the /words endpoint.
      required:
        - word
      properties:
        word:
          type: string
          description: The matched word or short phrase.
          example: giraffe
        score:
          type: integer
          description: Relationship-strength or popularity score; relative within the result set.
          example: 1075
        numSyllables:
          type: integer
          description: Syllable count (returned when `md=s` is requested).
          example: 2
        tags:
          type: array
          description: |
            Lexical tags returned when metadata flags are requested. May include
            parts-of-speech codes (`n`, `v`, `adj`, `adv`, `u`), pronunciation entries
            prefixed `pron:`, and frequency entries prefixed `f:`.
          items:
            type: string
          example:
            - n
            - "pron:JH ER0 AE1 F"
            - "f:0.422043"
        defs:
          type: array
          description: Definitions returned when `md=d` is requested. Each entry is prefixed by its part-of-speech code.
          items:
            type: string
          example:
            - "n\ttall spotted East African mammal with a long neck"
        defHeadword:
          type: string
          description: Base headword form returned for inflected words when definitions are requested.
    Suggestion:
      type: object
      description: A suggestion returned from the /sug endpoint.
      required:
        - word
      properties:
        word:
          type: string
          description: The suggested completion (may include a spelling correction or semantic fallback).
          example: prawn
        score:
          type: integer
          description: Popularity score; higher means more likely.
          example: 1500