Explain Regex API

The Explain Regex API converts a regular expression into a semantic explanation. This hosted API feature requires a regex101 Pro account.

Endpoint

Send a POST request to /api/explain.

The request body has these fields:

Field	Type	Required	Description
pattern	string	Yes	The regular expression to explain. The maximum length is 25,000 characters.
parserOptions	object	Yes	The flavor, delimiter, and flags for the parser.
format	text or json	No	The response format. The default value is text.
verbose	boolean	No	Includes supplemental details in text output. The default value is false.
indentSize	integer	No	The number of spaces for each text tree level. The range is 2-8. The default is 4.

Text response

When a person must read the explanation, use text output. The API text renderer uses short English sentences.

{
  "pattern": "^(?<word>[a-z]+)(?:\\s+\\k<word>)?$",
  "parserOptions": {
    "flavor": "pcre2",
    "delimiter": "/",
    "flags": "i"
  },
  "format": "text",
  "verbose": false,
  "indentSize": 4
}

The response has this form:

{
  "format": "text",
  "explanation": "^ — Asserts the start of the string.\n..."
}

The text output shows groups and character classes as parent lines. Quantifier lines appear before their contents.

The default output omits supplemental behavior and warnings. Set verbose to true to include these details.

Use indentSize to set the number of spaces for each tree level. This option applies only to text output.

JSON response

When an application must render the explanation, use JSON output. The JSON contains facts and does not contain presentation markup.

{
  "pattern": "[a-z]+",
  "parserOptions": {
    "flavor": "pcre2",
    "delimiter": "/",
    "flags": "i"
  },
  "format": "json"
}

This abridged response shows the form:

{
  "format": "json",
  "explanation": {
    "type": "regex-explanation",
    "pattern": "[a-z]+",
    "flavor": "pcre2",
    "flags": "i",
    "valid": true,
    "nodes": [
      {
        "type": "char-class",
        "kind": "left-bracket",
        "children": []
      }
    ],
    "errors": [],
    "globalFlags": [
      {
        "value": "i",
        "disabled": false
      }
    ]
  }
}

The nodes array is a recursive tree. Each node contains common parser facts and the facts for its token type.

For example, a text fact can include caseInsensitive and a character object. That object contains base10, base8, and base16 values.

The API schema describes the response envelope and the recursive node shape. Node objects can contain more semantic facts for their token type.

Use the type and kind fields to select the facts that your renderer understands. Ignore other node fields so new explanation facts do not break your client.

Invalid patterns

An invalid pattern still returns a successful explanation response. Its valid field is false, and its errors array contains the parser errors.

Text output shows each invalid token with a short error description. JSON output keeps the numeric parser error and its token facts.