{
  "openapi": "3.1.0",
  "info": {
    "title": "SuggestPassword API",
    "version": "1.0.0",
    "summary": "Free API for strong random passwords, passphrases and PIN codes.",
    "description": "Generates cryptographically secure passwords (PHP random_int, no modulo bias), diceware passphrases from the EFF large word list, and PIN codes. No API key, CORS enabled for every origin, rate-limited per IP. Generated values are never stored or logged. Every enabled character type is guaranteed to appear at least once.",
    "contact": {
      "name": "SuggestPassword",
      "url": "https://suggestpassword.com/contact"
    },
    "termsOfService": "https://suggestpassword.com/developers"
  },
  "externalDocs": {
    "description": "Documentation and examples",
    "url": "https://suggestpassword.com/developers"
  },
  "servers": [
    {
      "url": "https://api.suggestpassword.com"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "generatePassword",
        "summary": "Generate passwords, passphrases or PINs",
        "description": "Returns one or more random values. With no parameters you get one 20-character password with upper- and lowercase letters, digits and the basic symbols !#&.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "What to generate.",
            "schema": {
              "type": "string",
              "enum": [
                "password",
                "passphrase",
                "pin"
              ],
              "default": "password"
            }
          },
          {
            "name": "length",
            "in": "query",
            "required": false,
            "description": "Password: 4–128 characters (default 20). PIN: 4–12 digits (default 6). Ignored for passphrases.",
            "schema": {
              "type": "integer",
              "minimum": 4,
              "maximum": 128
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "description": "Number of results.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 1
            }
          },
          {
            "name": "upper",
            "in": "query",
            "required": false,
            "description": "Password only: include A–Z.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          },
          {
            "name": "lower",
            "in": "query",
            "required": false,
            "description": "Password only: include a–z.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          },
          {
            "name": "digits",
            "in": "query",
            "required": false,
            "description": "Password only: include 0–9.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          },
          {
            "name": "symbols",
            "in": "query",
            "required": false,
            "description": "Password only: none, basic (!#&) or all (!#&-=~@$%^*_+.?|).",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "basic",
                "all"
              ],
              "default": "basic"
            }
          },
          {
            "name": "no_ambiguous",
            "in": "query",
            "required": false,
            "description": "Password only: leave out look-alike characters 0 O o 1 l I |.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          },
          {
            "name": "words",
            "in": "query",
            "required": false,
            "description": "Passphrase only: number of words.",
            "schema": {
              "type": "integer",
              "minimum": 3,
              "maximum": 12,
              "default": 5
            }
          },
          {
            "name": "separator",
            "in": "query",
            "required": false,
            "description": "Passphrase only: what goes between the words.",
            "schema": {
              "type": "string",
              "enum": [
                "-",
                "space",
                ".",
                "_",
                "none"
              ],
              "default": "-"
            }
          },
          {
            "name": "capitalize",
            "in": "query",
            "required": false,
            "description": "Passphrase only: capitalise each word.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Passphrase only: add one random digit to a random word.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          },
          {
            "name": "advanced",
            "in": "query",
            "required": false,
            "deprecated": true,
            "description": "Legacy: advanced=true is the same as symbols=all.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated values",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "generated_password": "x7Kq#bT2mW!pZr9&LdYe",
                  "passwords": [
                    "x7Kq#bT2mW!pZr9&LdYe"
                  ],
                  "type": "password",
                  "entropy_bits": 119.7
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "length must be a whole number between 4 and 128"
                }
              }
            }
          },
          "405": {
            "description": "Only GET, HEAD and OPTIONS are allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this IP; slow down and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Result": {
        "type": "object",
        "required": [
          "generated_password",
          "passwords",
          "type",
          "entropy_bits"
        ],
        "properties": {
          "generated_password": {
            "type": "string",
            "description": "The first result."
          },
          "passwords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All results (count of them)."
          },
          "type": {
            "type": "string",
            "enum": [
              "password",
              "passphrase",
              "pin"
            ]
          },
          "entropy_bits": {
            "type": "number",
            "description": "Strength of each result in bits: log2 of the number of equally likely possibilities."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}