Explain Regex API
Use the Explain Regex API to turn a pattern into text or a structured explanation tree.
- Free
- Unavailable
- Pro
- Requires account
- Self-hosted
- Optional add-on
On regex101.com, this endpoint requires an authenticated Pro account. See API authentication.
On self-hosted deployments, the Explain Regex API entitlement controls access. The endpoint does not require account authentication there; configure deployment access controls accordingly.
Endpoint
Send POST https://regex101.com/api/explain with Content-Type: application/json. Use the deployment's base URL for a self-hosted instance.
| Field | Required | Meaning |
|---|---|---|
pattern | Yes | Pattern text, up to 25,000 characters. Do not include enclosing delimiters. |
parserOptions | Yes | Object containing flavor, flags, and delimiter. |
format | No | text or json; defaults to text. |
verbose | No | Include supplemental details in text output; defaults to false. |
indentSize | No | Spaces per text tree level, from 2 through 8; defaults to 4. |
The request body limit is 256 KiB. The live API schema defines valid flags and delimiters for each flavor.
Text response
Use this request body for a case-insensitive PCRE2 pattern:
{
"pattern": "[a-z]+",
"parserOptions": { "flavor": "pcre2", "flags": "i", "delimiter": "/" },
"format": "text"
}
Save the body as explain-request.json. If your client has securely supplied REGEX101_TOKEN, send the request:
: "${REGEX101_TOKEN:?Set REGEX101_TOKEN through your credential configuration}"
curl --fail-with-body \
--header "Authorization: Bearer $REGEX101_TOKEN" \
--header "Content-Type: application/json" \
--data-binary @explain-request.json \
https://regex101.com/api/explain
The response contains format: "text" and an explanation string. This sample returns the following explanation:
[a-z]+ — Character Class.
+ — Matches at least one character from the set below.
a-z — One character from "a" through "z".
Flags
Flag i (enabled) — Matches without case sensitivity.
Set verbose to true for supplemental behavior and warnings. verbose and indentSize affect text rendering only.
JSON response
Set format to json in the same request. The response contains an explanation object with these fields:
| Field | Meaning |
|---|---|
type | regex-explanation. |
pattern, flavor, flags | The pattern and parser configuration. |
summary | Pattern-level explanation content, or null. |
valid | Whether the parser found a valid pattern. |
nodes | Recursive explanation nodes. |
errors | Parser errors. |
globalFlags | Global flag facts. |
Each node has role, source, and content. The role determines its additional fields:
| Role | Additional fields |
|---|---|
parent | children, details, and lead. |
expandable | children, details, collapseByDefault, and childrenKind. |
container | continuation. |
leaf | None. |
source identifies syntax through its type, position, marker, and label fields. These positions refer to the pattern, not matched input.
content, summary, and details contain structured explanation content, not plain strings in every case.
Use role to choose how to render a node.
The live API schema describes content variants. Ignore unknown fields when you read a response.
Invalid patterns
An invalid regex can return HTTP 200 with an explanation. In JSON output, valid is false, and errors contains parser errors.
For example, submit [ with the same parser options. Text output describes the unclosed character class; JSON output retains the parser error.
Request validation is different from pattern validation:
| Result | What to verify |
|---|---|
400 | Required fields, supported flavor, valid flags, and delimiter. |
401 | A missing or expired credential where authentication is required. |
403 | Pro access or the deployment's Explain Regex API entitlement. |
413 | Request body size. |
200 with valid: false | The regex syntax in the selected flavor. |
The response error envelope is described in API errors.