API Reference

RegexLens exposes a REST API for authenticated integrations (saved snippets, analysis, AI chat, and more).

Base URL

https://regexlens.dev/api

For local development:

http://localhost:3000/api

Authentication

Session Cookie

When signed in via the web interface, your session cookie is automatically included in API requests.

API Token (Coming Soon)

Signed-in users will be able to generate API tokens for programmatic access.

Browser integration constraints

These routes are designed for the RegexLens web UI running on the same site origin:

• CSRF / Origin: POST, PUT, PATCH, and DELETE handlers require an Origin header that matches the site (enforceCsrfProtection). Pure server scripts or curl without Origin will receive HTTP 403 until dedicated token-based APIs ship.
• Rate limits: Authenticated routes enforce Redis-backed limits per client IP and per signed-in user ID (layered checks).
• JSON bodies: Mutation routes parse JSON with hard byte ceilings enforced while streaming the body (not only via Content-Length).

Endpoints

User profile

GET /api/me

Get the current signed-in user (if any).

Authentication: Optional (user is null when unauthenticated)

Response (authenticated):

{
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe",
    "image": "https://..."
  }
}

Response (unauthenticated):

{
  "user": null
}

Fixtures (public)

GET /api/fixtures/regexlens

Returns the built-in RegexLens fixture JSON used by the Fixtures panel in the workbench.

Authentication: Not required

Caching: Responses include Cache-Control: public, max-age=60.

Snippets

GET /api/snippets

List saved regex patterns.

Authentication: Required

Query Parameters:

Response:

{
 "items": [
  {
   "id": "snippet_123",
   "name": "Email Validation",
   "pattern": "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
   "flags": "gi",
   "description": "Basic email format validation",
   "tags": ["validation", "email"],
   "created_at": "2023-10-15T10:30:00Z",
   "updated_at": "2023-10-15T10:30:00Z"
  }
 ],
 "next_cursor": "cursor_abc123"
}

POST /api/snippets

Create a new saved pattern.

Authentication: Required

Request Body:

{
 "name": "Phone Number",
 "pattern": "\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}",
 "flags": "g",
 "description": "US phone number format",
 "tags": ["validation", "phone"]
}

Response: 201 Created

{
 "id": "snippet_456",
 "name": "Phone Number",
 "pattern": "\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}",
 "flags": "g",
 "description": "US phone number format",
 "tags": ["validation", "phone"],
 "created_at": "2023-10-15T11:00:00Z",
 "updated_at": "2023-10-15T11:00:00Z"
}

GET /api/snippets/:id

Get a specific pattern.

Authentication: Required

Response:

{
 "id": "snippet_123",
 "name": "Email Validation",
 "pattern": "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
 "flags": "gi",
 "description": "Basic email format validation",
 "tags": ["validation", "email"],
 "created_at": "2023-10-15T10:30:00Z",
 "updated_at": "2023-10-15T10:30:00Z"
}

PATCH /api/snippets/:id

Update a pattern.

Authentication: Required

Request Body: (all fields optional)

{
 "name": "Email Validation (Updated)",
 "pattern": "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
 "flags": "gi",
 "description": "Updated description",
 "tags": ["validation", "email", "updated"],
 "notes": "Added support for plus addressing"
}

Response:

{
 "id": "snippet_123",
 "name": "Email Validation (Updated)",
 ...
}

DELETE /api/snippets/:id

Delete a pattern.

Authentication: Required

Response: 204 No Content

GET /api/snippets/:id/versions

Get version history for a pattern.

Authentication: Required

Response:

{
 "items": [
  {
   "id": "version_789",
   "pattern": "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
   "flags": "gi",
   "notes": "Added plus addressing support",
   "created_at": "2023-10-15T11:00:00Z"
  },
  {
   "id": "version_456",
   "pattern": "^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
   "flags": "gi",
   "notes": null,
   "created_at": "2023-10-15T10:30:00Z"
  }
 ]
}

Export

POST /api/export

Export explanation in various formats.

Authentication: Required

Request Body:

{
 "format": "markdown",
 "title": "Email Validation",
 "pattern": "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
 "flags": "gi",
 "steps": [
  { "label": "Start of string", "depth": 0 },
  { "label": "One or more word characters...", "depth": 0, "detail": "Local part" }
 ],
 "warnings": [
  {
   "severity": "info",
   "title": "Unescaped dot",
   "message": "The dot matches any character",
   "hint": "Use \\. for literal dot"
  }
 ]
}

Formats: markdown, plain, pr_comment, notion

Response:

{
 "content": "# Email Validation\n\n## Pattern\n\n..."
}

Analyze

POST /api/analyze

Run server-side advanced analysis (same engine as the Safety tab). Returns a risk score, structured warnings, optional rewrite suggestions, and a complexity summary.

Authentication: Required (session cookie)

Request Body:

{
 "pattern": "^[\w.+-]+@[\w.-]+\.[a-zA-Z]{2,}$",
 "flags": "gi"
}

Success Response:

{
 "riskScore": 42,
 "warnings": [
  {
   "id": "nested-quantifiers",
   "severity": "danger",
   "title": "Nested quantifiers",
   "message": "May cause catastrophic backtracking on hostile input.",
   "hint": "Prefer possessive/atomic groups where supported, or simplify repetition.",
   "range": { "start": 0, "end": 5 }
  }
 ],
 "notes": [
  "Consider testing with long non-matching prefixes."
 ],
 "suggestions": [
  {
   "id": "rewrite-1",
   "title": "Prefer explicit character class",
   "description": "Replace alternation of single letters with `[abc]` when equivalent.",
   "caveat": "Check readability vs. performance tradeoffs."
  }
 ],
 "complexity": {
  "level": "medium",
  "factors": [
   "Multiple quantifiers",
   "Lookaround assertions"
  ]
 }
}

Fields may vary run-to-run; warnings / suggestions can be empty arrays. Severity uses info, warn, or danger.

AI chat

POST /api/ai/chat

Streaming AI assistant used by Regex Copilot. Signed-in only; uses a bring-your-own-key model where you supply your Anthropic API key via the X-Anthropic-Key request header. Your key is used for the single request and never stored or logged.

Authentication: Required (session cookie + X-Anthropic-Key header)

Headers:

Errors: 401 when unauthenticated or missing/invalid API key, 429 when rate-limited.

Error Responses

All errors follow this format:

{
 "error": "error_code",
 "message": "Human-readable message",
 "details": {}
}

Common Error Codes

| not_found | 404 | Resource not found | | rate_limited | 429 | Too many requests | | invalid_json | 400 | Malformed JSON body | | validation_error | 400 | Invalid input | | internal_error | 500 | Server error |

Rate Limits

* Values follow the api_free / export / ai_chat tiers in the server; exact headers are returned on each response.

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1697376000

Webhooks (Coming Soon)

Signed-in users will be able to configure webhooks for:

• Pattern created/updated/deleted
• Export completed