{
 "openapi": "3.1.0",
 "info": {
  "title": "Sieve API",
  "version": "1.0.0",
  "description": "Sieve runs a regular expression for real, on JavaScript's engine or on RE2 (Go), against strings that should and should not match, and shows each pass or fail with the matched text and groups.",
  "contact": {
   "name": "Clawhard Studio",
   "url": "https://clawhard.com",
   "email": "support@clawhard.com"
  }
 },
 "servers": [
  {
   "url": "https://sieve.clawhard.com"
  }
 ],
 "paths": {
  "/api/v1/test_regex": {
   "post": {
    "operationId": "test_regex",
    "summary": "Run a regular expression on test strings (JavaScript or RE2/Go) and check it for ReDoS",
    "description": "Use when you have written, been given or are about to commit a regular expression and need to know what it really matches, instead of predicting it (signals: \"write a regex for\", \"does this regex match\", \"validate emails/phone numbers/dates/slugs/URLs with a regex\", \"why doesn't my regex match\",…",
    "x-full-description": "Use when you have written, been given or are about to commit a regular expression and need to know what it really matches, instead of predicting it (signals: \"write a regex for\", \"does this regex match\", \"validate emails/phone numbers/dates/slugs/URLs with a regex\", \"why doesn't my regex match\", \"test this pattern\", \"regex for Go\", \"is this regex safe\", \"catastrophic backtracking\", \"convert this Python regex to JavaScript\"). Executes the pattern on the real engine: JavaScript (V8 RegExp, the engine in Chrome, Node.js and Cloudflare Workers; flags d g i m s u v y) or RE2 (re2js, with Go regexp parity: Go, RE2, Google Sheets and BigQuery syntax; flags i m s). Give strings that must match and strings that must not; each case comes back pass/fail with the matched text, index and capture groups (numbered and named), and why a \"should not match\" string matched (usually a missing ^...$). match: \"full\" tests the whole string. texts lists every match, replace_with shows the replacement ($1/$<name> in JavaScript, $1/${name} in Go). For JavaScript it also runs a ReDoS analysis (recheck): proven linear, or exponential/polynomial backtracking with a concrete attack string and the hot part of the pattern. Flags patterns that compile but mislead: ^a|b$ anchoring, \\A/\\Z/\\h read as letters, [[:alpha:]], {,3}, [A-z], unescaped dots before extensions. Invalid patterns return the engine's error and a hint (Python (?P<name>), (?i), possessive and atomic groups; lookarounds and backreferences in RE2). Example: {\"pattern\":\"[\\\\w.+-]+@[\\\\w-]+\\\\.[a-z]{2,}\",\"should_match\":[\"ann@example.com\"],\"should_not_match\":[\"ann@example\",\"see ann@x.io now\"]}. Does not run Python, PCRE, Java or .NET engines; it reports what differs for common constructs. Up to 100 strings of 20000 characters; on a ReDoS-vulnerable pattern, long strings are skipped instead of hanging. Returns: {valid, verdict: ok|warnings|redos|fails|invalid, summary, engine, engine_name, pattern, flags, match_mode, counts:{should_match, should_not_match, texts, passed, failed, skipped}, group_count, cases:[{text, length, expect: match|no_match|any, matched, pass (null = skipped), match_count, match:{text, index, end, groups?, named?}, matches? (texts only), why?, replaced?, skipped?}], warnings:[{rule, message, fix?, index?}], redos:{status: safe|vulnerable|unknown, complexity: linear|polynomial (degree n)|exponential|no attack found|unknown, attack?:{repr, length, string|null, sample}, hotspots?:[{start, end, text}], explanation?, fix_hint?, note?}|null, fix_message (ready-to-apply list, null when clean), error? and hint? (invalid patterns), notes, checked_at, open_url}",
    "x-openai-isConsequential": false,
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "pattern": {
          "type": "string",
          "minLength": 1,
          "maxLength": 5000,
          "description": "The regex source, e.g. \"^\\\\d{4}-\\\\d{2}$\" (JSON-escaped), or a JavaScript literal \"/^\\\\d+$/i\" (flags then come from the literal)."
         },
         "flags": {
          "type": "string",
          "maxLength": 8,
          "description": "JavaScript: any of d g i m s u v y. RE2: i m s. Default none."
         },
         "engine": {
          "type": "string",
          "enum": [
           "javascript",
           "re2"
          ],
          "description": "\"javascript\" (default; also TypeScript, Node.js, browsers, Deno, Bun) or \"re2\" (Go regexp, RE2, Google Sheets REGEXMATCH, BigQuery)."
         },
         "should_match": {
          "type": "array",
          "maxItems": 100,
          "items": {
           "type": "string",
           "maxLength": 20000
          },
          "description": "Strings the pattern must match (in match mode)."
         },
         "should_not_match": {
          "type": "array",
          "maxItems": 100,
          "items": {
           "type": "string",
           "maxLength": 20000
          },
          "description": "Strings the pattern must not match."
         },
         "texts": {
          "type": "array",
          "maxItems": 100,
          "items": {
           "type": "string",
           "maxLength": 20000
          },
          "description": "Strings to search; every match is listed with its groups (no pass/fail)."
         },
         "match": {
          "type": "string",
          "enum": [
           "search",
           "full"
          ],
          "description": "\"search\" (default): a match anywhere counts, like RegExp.test, re.search or Go MatchString. \"full\": the whole string must match, like Python re.fullmatch."
         },
         "replace_with": {
          "type": "string",
          "maxLength": 2000,
          "description": "Optional replacement; each case also returns the string with every match replaced."
         },
         "max_matches": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "description": "Most matches listed per text (default 10). match_count is always the full count."
         },
         "check_redos": {
          "type": "boolean",
          "description": "Run the ReDoS analysis (JavaScript engine). Default true."
         }
        },
        "required": [
         "pattern"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/check_redos": {
   "post": {
    "operationId": "check_redos",
    "summary": "Check regular expressions for ReDoS (catastrophic backtracking)",
    "description": "Use when a regular expression will run on user input or untrusted data (form validation, request routing, log parsing, WAF or search rules) and must not hang the server, or when reviewing a codebase's regexes for ReDoS (signals: \"is this regex safe\", \"ReDoS\", \"catastrophic backtracking\", \"regex…",
    "x-full-description": "Use when a regular expression will run on user input or untrusted data (form validation, request routing, log parsing, WAF or search rules) and must not hang the server, or when reviewing a codebase's regexes for ReDoS (signals: \"is this regex safe\", \"ReDoS\", \"catastrophic backtracking\", \"regex hangs\", \"CPU spike on validation\", \"security review of regexes\", \"(a+)+\"). Analyzes 1 to 20 patterns with recheck (automaton analysis with a fuzzing fallback) for backtracking engines with JavaScript syntax, and returns per pattern: safe (proven linear, or no attack found when backreferences or lookarounds force fuzzing), or vulnerable with the complexity (exponential, or polynomial with its degree), a concrete attack string (repr like 'a'.repeat(31) + '\\\\x00', plus the string itself when short), the hot part of the pattern and a fix hint. Example: {\"patterns\":[\"^(a+)+$\",\"/^([a-z]+\\\\s)*$/\",\"^[\\\\w.+-]+@[\\\\w-]+\\\\.[\\\\w.-]+$\"]}. Python re, PCRE, Java, .NET and Ruby backtrack the same way on these constructs; RE2, Go regexp and Rust regex are linear-time and not affected. To also run the pattern on test strings, use sieve_test_regex. Returns: {summary, counts:{patterns, vulnerable, safe, unknown, invalid}, results:[{pattern, flags, valid, status: safe|vulnerable|unknown|invalid, complexity, attack?:{repr, length, string|null, sample}, hotspots?:[{start, end, text}], explanation?, fix_hint?, note?, error?, hint?}], engine_note, analyzer, checked_at}",
    "x-openai-isConsequential": false,
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "patterns": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "items": {
           "type": "string",
           "minLength": 1,
           "maxLength": 5000
          },
          "description": "Regex sources (\"^(a+)+$\") or JavaScript literals (\"/^(a+)+$/i\")."
         },
         "flags": {
          "type": "string",
          "maxLength": 8,
          "description": "Flags for every pattern given as a raw source (literals keep their own). JavaScript flags d g i m s u v y."
         }
        },
        "required": [
         "patterns"
        ]
       }
      }
     }
    }
   }
  }
 },
 "externalDocs": {
  "description": "llms.txt",
  "url": "https://sieve.clawhard.com/llms.txt"
 }
}