---
title: "Use this when you need the true matches of a JavaScript regular expression rather than predicting regex behavior yourself, which is easy to get wrong."
method: POST
path: "/v1/test_regex"
tags: ["developer"]
---

# Use this when you need the true matches of a JavaScript regular expression rather than predicting regex behavior yourself, which is easy to get wrong.

`POST /v1/test_regex`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/test_regex`
- Auth: none declared

Use this when you need the true matches of a JavaScript regular expression rather than predicting regex behavior yourself, which is easy to get wrong. Deterministic: same input, same output. Returns every match with its index, length, matched text, positional capture groups (null for a group that didn't participate), and named groups (an object, or null when the pattern has none). Without the g flag only the first match is returned; with g all matches are collected, capped at 10,000 with truncated=true. Inputs are length-bounded (pattern 2,000 chars, text 50,000 chars) as a ReDoS guard. Example: pattern (?<y>\d{4})-(?<m>\d{2}) over "2024-01" with flag g -> matchCount 1, match "2024-01", groups ["2024","01"], named {y:"2024",m:"01"}.

## Request body

- object
  - `pattern` string, required: Regular expression source (no delimiters).
  - `text` string, required: String to search.
  - `flags` string: Any of g i m s u v y.

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `pattern` string, required: The regex source that was compiled (echoed back).
    - `flags` string, required: The flags applied (subset of g i m s u v y).
    - `matchCount` integer, required: Number of matches returned in the matches array.
    - `truncated` boolean, required: True if the 10,000-match cap was hit and further matches were dropped.
    - `matches` object[], required: One entry per match, in order of appearance.
      - `index` integer, required: Zero-based start offset of the match in the text.
      - `length` integer, required: Length of the matched substring.
      - `match` string, required: The full matched substring (group 0).
      - `groups` string[], required: Positional capture groups 1..n; a non-participating group is null.
      - `named` object, nullable, required: Named capture groups as name->value, or null when the pattern defines none; a non-participating named group is null.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)