{
  "openapi": "3.0.3",
  "info": {
    "title": "AI Name Suggestion",
    "description": "Send a domain name or a description of a business and get back available domain names that suit it. Both requests take the same fields: GET puts them in the address, and POST sends them as JSON."
  },
  "x-meridian-auth": {
    "title": "Authentication",
    "description": "Send your username and password with each request, in an Authorization header. The header reads Basic, a space, then your username and password joined by a colon and encoded as Base64. Most HTTP clients build it from the two values for you, such as curl with its -u option."
  },
  "x-meridian-first-request": {
    "operation": "GET /v1/suggest",
    "description": "It takes a few words about a business and answers with names that suit it. Here it is with your username and password in place:",
    "request": "GET /v1/suggest?q=a%20coffee%20shop%20in%20paris\nAuthorization: Basic base64(USERNAME:PASSWORD)"
  },
  "components": {
    "securitySchemes": {
      "usernameAndPassword": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "usernameAndPassword": []
    }
  ],
  "paths": {
    "/v1/suggest": {
      "get": {
        "summary": "Suggest domain names.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Domain name or business description. At most 500 characters, after space at either end is removed. A longer value is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_include",
            "in": "query",
            "required": false,
            "description": "Additional TLDs to include, comma-separated (e.g. de,co.uk). Use to add ccTLDs not returned by default. A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_exclude",
            "in": "query",
            "required": false,
            "description": "TLDs to exclude from results, comma-separated (e.g. xyz,info). A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_restrict",
            "in": "query",
            "required": false,
            "description": "Restrict results exclusively to these TLDs, comma-separated (e.g. com,net). Overrides tld_include and tld_exclude. A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sprompt",
            "in": "query",
            "required": false,
            "description": "Append an optional system prompt to guide the response at the higher level. It is the place for a constraint such as a style, a theme or the language of the answer. The service answers in any language: \"Bitte verwende nur Deutsch. Antworte nicht auf Englisch.\" asks for German. At most 300 characters. A longer value is rejected. When omitted, it is empty.",
            "schema": {
              "type": "string",
              "default": ""
            }
          }
        ],
        "x-meridian-request": "GET /v1/suggest?q=a%20coffee%20shop%20in%20berlin&sprompt=Bitte%20verwende%20nur%20Deutsch.%20Antworte%20nicht%20auf%20Englisch.",
        "x-meridian-response": "{\n  \"suggestions\": [\n    {\n      \"sld\": \"example\",\n      \"tld\": \"com\"\n    }\n  ]\n}",
        "x-meridian-errors": [
          {
            "status": "400",
            "description": "The request failed the checks other than length: q is missing, or a TLD list in which every value is unusable."
          },
          {
            "status": "413",
            "description": "q is longer than 500 characters, or sprompt is longer than 300."
          },
          {
            "status": "401",
            "description": "The request did not carry a username and password the service could use."
          },
          {
            "status": "403",
            "description": "The username is not one this service knows."
          },
          {
            "status": "500",
            "description": "The service could not complete the request."
          },
          {
            "status": "503",
            "description": "The availability check is limiting requests."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "description": "The names returned.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sld": {
                            "type": "string",
                            "description": "The name without its top-level domain."
                          },
                          "tld": {
                            "type": "string",
                            "description": "The top-level domain of the suggestion."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/recommend": {
      "post": {
        "summary": "Suggest domain names from the same fields, sent as JSON.",
        "parameters": [
          {
            "name": "q",
            "in": "body",
            "required": true,
            "description": "Domain name or business description. At most 500 characters, after space at either end is removed. A longer value is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_include",
            "in": "body",
            "required": false,
            "description": "Additional TLDs to include, comma-separated (e.g. de,co.uk). Use to add ccTLDs not returned by default. A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_exclude",
            "in": "body",
            "required": false,
            "description": "TLDs to exclude from results, comma-separated (e.g. xyz,info). A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tld_restrict",
            "in": "body",
            "required": false,
            "description": "Restrict results exclusively to these TLDs, comma-separated (e.g. com,net). Overrides tld_include and tld_exclude. A value in which every top-level domain is unusable is rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sprompt",
            "in": "body",
            "required": false,
            "description": "Append an optional system prompt to guide the response at the higher level. It is the place for a constraint such as a style, a theme or the language of the answer. The service answers in any language: \"Bitte verwende nur Deutsch. Antworte nicht auf Englisch.\" asks for German. At most 300 characters. A longer value is rejected. When omitted, it is empty.",
            "schema": {
              "type": "string",
              "default": ""
            }
          }
        ],
        "x-meridian-request": "{\n  \"q\": \"a coffee shop in berlin\",\n  \"tld_include\": \"de\",\n  \"sprompt\": \"Bitte verwende nur Deutsch. Antworte nicht auf Englisch.\"\n}",
        "x-meridian-response": "{\n  \"suggestions\": [\n    {\n      \"sld\": \"example\",\n      \"tld\": \"com\"\n    }\n  ]\n}",
        "x-meridian-errors": [
          {
            "status": "400",
            "description": "q is missing or longer than 500 characters, sprompt is longer than 300 characters, or every value in a TLD list is unusable. A value that is too long is a 400 here, where GET /v1/suggest answers it with a 413."
          },
          {
            "status": "401",
            "description": "The request did not carry a username and password the service could use."
          },
          {
            "status": "403",
            "description": "The username is not one this service knows."
          },
          {
            "status": "500",
            "description": "The service could not complete the request."
          },
          {
            "status": "503",
            "description": "The availability check is limiting requests."
          }
        ],
        "responses": {
          "200": {
            "description": "The names found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "description": "The names returned.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sld": {
                            "type": "string",
                            "description": "The name without its top-level domain."
                          },
                          "tld": {
                            "type": "string",
                            "description": "The top-level domain of the suggestion."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
