{
  "openapi": "3.0.3",
  "info": {
    "title": "Name Suggestion",
    "description": "Send a word, a phrase or a name and get back domain names that suit it, check whether the names you have in mind are available, and list the top-level domains the service can suggest."
  },
  "x-meridian-auth": {
    "title": "Authentication",
    "description": "Send authtoken with each request except the list of top-level domains, which needs no token. The spelling authToken is also accepted."
  },
  "x-meridian-first-request": {
    "operation": "GET /v5/recommend",
    "description": "It takes a word and answers with names. Every example below already carries authtoken in its address, so each is ready to send once your token takes the place of YOUR_TOKEN."
  },
  "paths": {
    "/v5/recommend": {
      "get": {
        "summary": "Suggest domain names from a word, a phrase or a name.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The words to suggest names from: a domain, a word or a phrase. Required. A query the service cannot use, or one longer than 63 characters after it is cleaned, is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "authtoken",
            "in": "query",
            "required": true,
            "description": "The access token for this account. The spelling authToken is also accepted. Send it once.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_results",
            "in": "query",
            "required": false,
            "description": "How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "func",
            "in": "query",
            "required": false,
            "description": "Which names to produce. 0, the default, returns the exact name and variations on it. 1 returns the exact name only, and is what an omitted func is read as when no_suggestions is yes. 2 leaves the exact name out, and is what an omitted func is read as when only_suggestions is yes.",
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "no_suggestions",
            "in": "query",
            "required": false,
            "description": "When this is yes and func is omitted, func is read as 1. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "only_suggestions",
            "in": "query",
            "required": false,
            "description": "When this is yes and func is omitted, and no_suggestions is not yes, func is read as 2. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "adult",
            "in": "query",
            "required": false,
            "description": "When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "no_idn",
            "in": "query",
            "required": false,
            "description": "When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "premium_ok",
            "in": "query",
            "required": false,
            "description": "When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "any_status",
            "in": "query",
            "required": false,
            "description": "When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.",
            "schema": {
              "type": "string",
              "default": "ok"
            }
          },
          {
            "name": "custom_tlds",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_ok",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_no",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_only",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "description": "Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.",
            "schema": {
              "type": "string",
              "default": "en,de,es,it,fr,pt,nl,sv,da,pl,no"
            }
          },
          {
            "name": "min_confidence",
            "in": "query",
            "required": false,
            "description": "The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.",
            "schema": {
              "type": "number",
              "default": 0
            }
          },
          {
            "name": "fad_pref",
            "in": "query",
            "required": false,
            "description": "A prefix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fad_suff",
            "in": "query",
            "required": false,
            "description": "A suffix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-meridian-request": "GET /v5/recommend?q=locksmith&authtoken=YOUR_TOKEN",
        "x-meridian-response": "[\n  {\n    \"Domain\": \"example.com\",\n    \"Type\": 0,\n    \"TLD\": \"com\",\n    \"ConfidenceScore\": 0.5,\n    \"Keys\": [\n      \"example\"\n    ],\n    \"Variations\": [],\n    \"Data\": [\n      {\n        \"Name\": \"length\",\n        \"Data\": 7\n      },\n      {\n        \"Name\": \"status\",\n        \"Data\": \"ok\"\n      }\n    ]\n  }\n]",
        "x-meridian-errors": [
          {
            "status": "200",
            "description": "The names found. If the request runs out of time, this is still 200 and holds the names found before it stopped."
          },
          {
            "status": "400",
            "description": "A parameter the service cannot read: a missing q, a status it does not know, a max_results or min_confidence that is not a number, a language it does not accept, custom_tlds or tld_only in which every top-level domain is unusable, or the token sent twice."
          },
          {
            "status": "401",
            "description": "The token is missing, or it is not a token the service knows."
          },
          {
            "status": "503",
            "description": "The service is out of capacity."
          },
          {
            "status": "429",
            "description": "More than 10 requests a second, or a burst of more than 30, was refused."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "Domain": {
                        "type": "string",
                        "description": "The suggested domain name."
                      },
                      "Type": {
                        "type": "integer",
                        "description": "1 when the suggestion is the exact name that was asked for, otherwise 0."
                      },
                      "TLD": {
                        "type": "string",
                        "description": "The top-level domain."
                      },
                      "ConfidenceScore": {
                        "type": "number",
                        "description": "How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places."
                      },
                      "Keys": {
                        "type": "array",
                        "description": "The keywords the suggestion was built from.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "Variations": {
                        "type": "array",
                        "description": "The variation codes applied to the name.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "Data": {
                        "type": "array",
                        "description": "Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.",
                        "items": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v5/fad": {
      "post": {
        "summary": "Suggest domain names, and also return the prefixes, suffixes, synonyms and top-level domains used.",
        "parameters": [
          {
            "name": "q",
            "in": "body",
            "required": true,
            "description": "The words to suggest names from: a domain, a word or a phrase. Required. A query the service cannot use, or one longer than 63 characters after it is cleaned, is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "authtoken",
            "in": "body",
            "required": true,
            "description": "The access token for this account. The spelling authToken is also accepted. Send it once.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_results",
            "in": "body",
            "required": false,
            "description": "How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "func",
            "in": "body",
            "required": false,
            "description": "Which names to produce. 0, the default, returns the exact name and variations on it. 1 returns the exact name only, and is what an omitted func is read as when no_suggestions is yes. 2 leaves the exact name out, and is what an omitted func is read as when only_suggestions is yes.",
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "no_suggestions",
            "in": "body",
            "required": false,
            "description": "When this is yes and func is omitted, func is read as 1. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "only_suggestions",
            "in": "body",
            "required": false,
            "description": "When this is yes and func is omitted, and no_suggestions is not yes, func is read as 2. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "adult",
            "in": "body",
            "required": false,
            "description": "When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "no_idn",
            "in": "body",
            "required": false,
            "description": "When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "premium_ok",
            "in": "body",
            "required": false,
            "description": "When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "any_status",
            "in": "body",
            "required": false,
            "description": "When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "body",
            "required": false,
            "description": "Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.",
            "schema": {
              "type": "array"
            }
          },
          {
            "name": "custom_tlds",
            "in": "body",
            "required": false,
            "description": "Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_ok",
            "in": "body",
            "required": false,
            "description": "Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_no",
            "in": "body",
            "required": false,
            "description": "Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_only",
            "in": "body",
            "required": false,
            "description": "Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "languages",
            "in": "body",
            "required": false,
            "description": "Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.",
            "schema": {
              "type": "string",
              "default": "en,de,es,it,fr,pt,nl,sv,da,pl,no"
            }
          },
          {
            "name": "min_confidence",
            "in": "body",
            "required": false,
            "description": "The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.",
            "schema": {
              "type": "number",
              "default": 0
            }
          },
          {
            "name": "fad_pref",
            "in": "body",
            "required": false,
            "description": "A prefix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fad_suff",
            "in": "body",
            "required": false,
            "description": "A suffix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fad_syn",
            "in": "body",
            "required": false,
            "description": "An object mapping a word to a list of synonyms. Send it in the JSON body.",
            "schema": {
              "type": "object"
            }
          }
        ],
        "x-meridian-request": "{\n  \"q\": \"locksmith\",\n  \"authtoken\": \"YOUR_TOKEN\",\n  \"fad_syn\": {\n    \"lock\": [\n      \"secure\"\n    ]\n  }\n}",
        "x-meridian-response": "{\n  \"suggestions\": [\n    {\n      \"Domain\": \"example.com\",\n      \"Type\": 0,\n      \"TLD\": \"com\",\n      \"ConfidenceScore\": 0.5,\n      \"Keys\": [\n        \"example\"\n      ],\n      \"Variations\": [],\n      \"Data\": [\n        {\n          \"Name\": \"length\",\n          \"Data\": 7\n        },\n        {\n          \"Name\": \"status\",\n          \"Data\": \"ok\"\n        }\n      ]\n    }\n  ],\n  \"FAD\": [\n    {\n      \"Name\": \"prefixes\",\n      \"Data\": []\n    },\n    {\n      \"Name\": \"suffixes\",\n      \"Data\": []\n    },\n    {\n      \"Name\": \"synonyms\",\n      \"Data\": {\n        \"lock\": [\n          \"secure\"\n        ]\n      }\n    },\n    {\n      \"Name\": \"tlds\",\n      \"Data\": [\n        \"com\"\n      ]\n    }\n  ]\n}",
        "x-meridian-errors": [
          {
            "status": "200",
            "description": "The names found, with the prefixes, suffixes, synonyms and top-level domains used. If the request runs out of time, this is still 200 and holds what was found before it stopped."
          },
          {
            "status": "400",
            "description": "The body is not JSON, or a parameter the service cannot read, including a missing q or the token sent twice."
          },
          {
            "status": "401",
            "description": "The token is missing, or it is not a token the service knows."
          },
          {
            "status": "503",
            "description": "The service is out of capacity."
          },
          {
            "status": "429",
            "description": "More than 10 requests a second, or a burst of more than 30, was refused."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "description": "The same name objects GET /v5/recommend returns. Each Data list also includes stamps.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "Domain": {
                            "type": "string",
                            "description": "The suggested domain name."
                          },
                          "Type": {
                            "type": "integer",
                            "description": "1 when the suggestion is the exact name that was asked for, otherwise 0."
                          },
                          "TLD": {
                            "type": "string",
                            "description": "The top-level domain."
                          },
                          "ConfidenceScore": {
                            "type": "number",
                            "description": "How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places."
                          },
                          "Keys": {
                            "type": "array",
                            "description": "The keywords the suggestion was built from.",
                            "items": {
                              "type": "string"
                            }
                          },
                          "Variations": {
                            "type": "array",
                            "description": "The variation codes applied to the name.",
                            "items": {
                              "type": "string"
                            }
                          },
                          "Data": {
                            "type": "array",
                            "description": "Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "FAD": {
                      "type": "array",
                      "description": "The prefixes, suffixes, synonyms and top-level domains used across the answer. Each item has Name and Data. The names are prefixes, suffixes, synonyms and tlds.",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v5/availability": {
      "get": {
        "summary": "Check the names you send.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The name to check. Required. Repeat the parameter to check more than one name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "authtoken",
            "in": "query",
            "required": true,
            "description": "The access token for this account. The spelling authToken is also accepted. Send it once.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_results",
            "in": "query",
            "required": false,
            "description": "How many names to return. When omitted, the service uses 50, except when status is only reg, when it uses 10. A value above 200 is read as 200. A value that is not a positive whole number is rejected.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "func",
            "in": "query",
            "required": false,
            "description": "Optional. When omitted, it is read as 3, and 3 is the only value accepted. Any other value is rejected.",
            "schema": {
              "type": "string",
              "default": "3"
            }
          },
          {
            "name": "adult",
            "in": "query",
            "required": false,
            "description": "When this is yes, adult top-level domains may be included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "no_idn",
            "in": "query",
            "required": false,
            "description": "When this is yes, internationalized names are left out. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "premium_ok",
            "in": "query",
            "required": false,
            "description": "When this is yes, premium names are included as well as the statuses asked for. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "any_status",
            "in": "query",
            "required": false,
            "description": "When this is yes, every availability status is included. 1, true or True means yes. Omitting it, or any other value, means no.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Which availability to return. Accepted values are ok, reg, pre and res. When omitted, ok. Repeat the parameter to ask for more than one. An unrecognised value is rejected. On POST /v5/fad, pass status as a list of these values.",
            "schema": {
              "type": "string",
              "default": "ok"
            }
          },
          {
            "name": "custom_tlds",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to use. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_ok",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to allow in addition to the account's set. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_no",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to leave out. Entries the service cannot use are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_only",
            "in": "query",
            "required": false,
            "description": "Comma-separated top-level domains to use and no others. A value in which every entry is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "description": "Comma-separated language codes. When omitted, the service uses en, de, es, it, fr, pt, nl, sv, da, pl and no. A code it does not accept is rejected.",
            "schema": {
              "type": "string",
              "default": "en,de,es,it,fr,pt,nl,sv,da,pl,no"
            }
          },
          {
            "name": "min_confidence",
            "in": "query",
            "required": false,
            "description": "The lowest score to return, from 0 to 0.99. When omitted, 0. A value above 1 is read as 0.99. A value below 0 is read as 0. A value that is not a number is rejected.",
            "schema": {
              "type": "number",
              "default": 0
            }
          },
          {
            "name": "fad_pref",
            "in": "query",
            "required": false,
            "description": "A prefix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fad_suff",
            "in": "query",
            "required": false,
            "description": "A suffix to apply. Repeat the parameter for more than one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-meridian-request": "GET /v5/availability?q=locksmith.com&func=3&authtoken=YOUR_TOKEN",
        "x-meridian-response": "[\n  {\n    \"Domain\": \"example.com\",\n    \"Type\": 0,\n    \"TLD\": \"com\",\n    \"ConfidenceScore\": 0.5,\n    \"Keys\": [\n      \"example\"\n    ],\n    \"Variations\": [],\n    \"Data\": [\n      {\n        \"Name\": \"length\",\n        \"Data\": 7\n      },\n      {\n        \"Name\": \"status\",\n        \"Data\": \"ok\"\n      }\n    ]\n  }\n]",
        "x-meridian-errors": [
          {
            "status": "200",
            "description": "The names found. If the request runs out of time, this is still 200 and holds the names found before it stopped."
          },
          {
            "status": "400",
            "description": "A parameter the service cannot read, including a missing q, a func other than 3, a status it does not know, or the token sent twice."
          },
          {
            "status": "401",
            "description": "The token is missing, or it is not a token the service knows."
          },
          {
            "status": "503",
            "description": "The service is out of capacity."
          },
          {
            "status": "429",
            "description": "More than 10 requests a second, or a burst of more than 30, was refused."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "Domain": {
                        "type": "string",
                        "description": "The suggested domain name."
                      },
                      "Type": {
                        "type": "integer",
                        "description": "1 when the suggestion is the exact name that was asked for, otherwise 0."
                      },
                      "TLD": {
                        "type": "string",
                        "description": "The top-level domain."
                      },
                      "ConfidenceScore": {
                        "type": "number",
                        "description": "How closely the suggestion matches what was asked. 1 when the score is 1 or higher, otherwise the score to three decimal places."
                      },
                      "Keys": {
                        "type": "array",
                        "description": "The keywords the suggestion was built from.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "Variations": {
                        "type": "array",
                        "description": "The variation codes applied to the name.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "Data": {
                        "type": "array",
                        "description": "Facts about the name. Each item has Name and Data. The names are length, keyscount, bad, dash, in_ga, idn and status.",
                        "items": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v5/tlds": {
      "get": {
        "summary": "List the top-level domains the service can use. Each value is zone or meta. This request needs no token.",
        "parameters": [],
        "x-meridian-request": "GET /v5/tlds",
        "x-meridian-response": "{\n  \"tlds\": {\n    \"com\": \"zone\"\n  }\n}",
        "x-meridian-errors": [
          {
            "status": "200",
            "description": "The top-level domains, each marked zone or meta."
          },
          {
            "status": "429",
            "description": "More than 10 requests a second, or a burst of more than 30, was refused."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tlds": {
                      "type": "object",
                      "description": "Each top-level domain the service can use, mapped to zone or meta.",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
