← Back to blog

Regex Tester API: Test Patterns with curl and Python

October 12, 2026 · Eric · 6 min read

A regular expression is the cheapest parser most of us own. It is also the easiest way to freeze a runtime: one nested quantifier over a long enough string and your event loop is gone. The Regex Tester on Agent Media Tools exists so you can test a pattern somewhere that is allowed to fail — every evaluation runs in an isolated worker thread with a hard 250 ms timeout, and the response tells you exactly what matched, where, and which groups captured what.

This guide covers the two real endpoints behind that tool, POST /api/regex/test and GET /api/regex/reference, with curl and Python examples you can copy. No SDK, no key required to start, and every claim below is checked against the shipped route code.

Why test a regex over an API instead of in-process

The two endpoints

Method & pathPurposeAuth
POST /api/regex/testRun a pattern against text; returns matches, captures, groups, and rangesNone to start
GET /api/regex/referenceReturns a JSON cheat sheet: anchors, character classes, quantifiers, groups, flagsNone to start

Both are free-tier tools. The Regex Tester also ships as a browser panel in the toolbox, under the Web group.

Step 1: Run a pattern with curl

Send pattern, flags, and text as a JSON body:

curl -s https://agentmediatools.com/api/regex/test \
  -H 'Content-Type: application/json' \
  -d '{
    "pattern": "(?<user>[a-z0-9._%+-]+)@(?<domain>[a-z0-9.-]+\\.[a-z]{2,})",
    "flags": "gi",
    "text": "Ping ada@example.com and ops@agentmediatools.com"
  }'

A successful call returns the matches plus counters. Trimmed example response:

{
  "success": true,
  "pattern": "(?<user>[a-z0-9._%+-]+)@(?<domain>[a-z0-9.-]+\\.[a-z]{2,})",
  "flags": "gi",
  "matches_found": 2,
  "truncated": false,
  "matches": [
    {
      "index": 5,
      "length": 15,
      "full": "ada@example.com",
      "groups": { "user": "ada", "domain": "example.com" },
      "captures": ["ada", "example.com"]
    }
  ],
  "ranges": [[5, 20]],
  "text_length": 48
}

Step 2: Read the response fields

One detail worth knowing: the server defaults to global matching when you omit flags, but the response echoes the flags string you actually sent (an empty string if you sent none). Pass flags explicitly whenever you plan to store or display that value.

Step 3: Named groups turn a match into a record

Named groups are the difference between "something matched" and "here is the row". A log line, a version string, or an invoice number each becomes a dictionary key instead of captures[3]:

curl -s https://agentmediatools.com/api/regex/test \
  -H 'Content-Type: application/json' \
  -d '{
    "pattern": "INV-(?<year>[0-9]{4})-(?<seq>[0-9]{4,6})",
    "flags": "g",
    "text": "paid INV-2026-004213, pending INV-2026-000918"
  }'

Each entry in matches then carries { "year": "2026", "seq": "004213" } in groups. Pair that with the offsets in ranges and you can highlight, redact, or rewrite the original text on your side with confidence.

Step 4: Validate patterns in Python before you ship them

Regex bugs are usually patterns that match more than you meant, or that explode on a hostile input. A small probe function catches both:

import requests

API = "https://agentmediatools.com/api/regex/test"

def probe(pattern, text, flags="g", timeout=15):
    r = requests.post(
        API,
        json={"pattern": pattern, "flags": flags, "text": text},
        timeout=timeout,
    )
    data = r.json()
    if not data.get("success"):
        return {"ok": False, "status": r.status_code, "error": data.get("error")}
    return {
        "ok": True,
        "count": data["matches_found"],
        "truncated": data["truncated"],
        "first": data["matches"][0]["groups"] if data["matches"] else None,
    }

sample = """2026-10-12 shipped
2026-10-11 rolled back
not a date: 12/10/2026
2026-10-09 shipped"""

for name, pattern in {
    "iso_date": r"(?<y>[0-9]{4})-(?<m>[0-9]{2})-(?<d>[0-9]{2})",
    "greedy_capture": r"(?<whole>.*)",
    "catastrophic": r"(a+)+$",
}.items():
    print(name, probe(pattern, sample))

print("hostile input:", probe(r"(a+)+$", "a" * 40 + "X"))

The first two calls return normal match data. The last one is a classic catastrophic-backtracking shape: it does not hang your machine, it comes back as an error, because the worker thread is killed at the timeout. That is exactly the signal you want during review — a pattern that fails here will eventually fail in production on an input you did not imagine.

Step 5: Hand the model a reference instead of hoping

Language models are confident about regex syntax and frequently wrong about it — flatteringly so with lookbehinds and named groups. The reference endpoint returns the syntax table as JSON, so you can fetch it once, cache it, and paste it into your agent's context:

curl -s https://agentmediatools.com/api/regex/reference | python3 -m json.tool | head -25

The payload groups anchors (^, $, \b), character classes, quantifiers, group forms — capturing, non-capturing, lookahead, negative lookahead, lookbehind, negative lookbehind, and named groups — and the supported flags (g, i, m, s, u, y). A grounded model writes fewer patterns that error on the first call, and the patterns it does write can be verified immediately against the same service.

Errors and input limits

SituationHTTP statusWhat comes back
Pattern will not compile400success:false and Invalid regex: …
Execution exceeds 250 ms422Regex execution timed out
Pattern longer than 500 characters400pattern too long (max 500 characters)
Text longer than 20,000 characters400text too long (max 20,000 characters)
pattern or text missing200success:false with pattern required / text required

Note the last row: missing input is reported with success:false rather than an error status. Branch on the success field, not only on the HTTP code, or you will happily process an empty match list that never existed.

Free limits worth designing around

What this API is not

Put it to work

Regex testing is one of those small deterministic capabilities that make an agent pipeline trustworthy: it turns "the model wrote a pattern" into "the pattern was executed, capped, timed out if needed, and reported with offsets". Start with curl against a string you already have, wrap it in the Python probe, and keep the reference payload in your prompt budget.

Test a pattern in the browser, then automate it

Open the Regex Tester in the toolbox to try a pattern interactively, or call the same endpoint from your scripts and agents.

Open toolbox