Workspace API

Use the workspace API to read saved regexes, create workspaces, and add versions from your application. This API exchanges workspace content with regex101. Regex matching runs locally in the browser editor.

Free: Per operation
Pro: Per operation
Self-hosted: Per operation

Compare plans

The interactive API reference describes the available endpoints and schemas. Download its OpenAPI JSON for client tooling.

From version 14.2.1, agents and client tools can also use the OpenAPI YAML.

Use the reference for complete schemas and additional routes. The examples below cover regular workspaces.

For an AI client, see MCP setup. For unsaved editor links, see URL parameters.

Routes

All paths below use https://regex101.com. For a self-hosted instance, use its base URL and deployed API reference.

Method and path	Operation
`GET /api/workspace/{permalinkFragment}/{version}`	Read one version.
`GET /api/workspace/{permalinkFragment}`	List available versions.
`POST /api/workspace`	Create a workspace or add a version.
`DELETE /api/workspace`	Delete a workspace with its delete code.
`DELETE /api/workspace/{version}`	Delete one version with its version delete code.

The /api/regex paths are compatibility aliases for /api/workspace. Use /api/workspace in new integrations.

Authentication

The website uses a secure session cookie. Compatible MCP clients use browser sign-in and store a bearer token. See MCP server for connection instructions.

If your client supplies a bearer token for API use, send it in the Authorization header. A bearer request does not need a Cookie header.

Treat the token like a password. Store it outside source control, use it only over HTTPS, and do not include it in URLs or logs:

Authorization: Bearer <token>

The authenticated examples assume that your environment already contains REGEX101_TOKEN. No token is included in these examples.

An invalid supplied bearer header causes 401, even for a public operation. Omit authentication for public reads when no credential is needed.

Example prerequisites

Use cURL with --fail-with-body, Node.js with global fetch, or Python with the requests package installed.

Set WORKSPACE_ID and WORKSPACE_VERSION from a workspace URL you can access. For /r/AbC123/1, the values are AbC123 and 1.

Replace AbC123 with your workspace's identifier.

Get a workspace

Use the workspace permalink fragment and version from a regex101 URL. Authentication is optional for public workspaces and required when the requested workspace is private. These examples request a public workspace without an Authorization header.

cURL
Node.js
Python

: "${WORKSPACE_ID:?Set WORKSPACE_ID from your workspace URL}"
: "${WORKSPACE_VERSION:?Set WORKSPACE_VERSION from your workspace URL}"
curl --fail-with-body \
  "https://regex101.com/api/workspace/$WORKSPACE_ID/$WORKSPACE_VERSION"

const workspaceId = process.env.WORKSPACE_ID
const workspaceVersion = process.env.WORKSPACE_VERSION
if (!workspaceId || !workspaceVersion) {
  throw new Error('Set WORKSPACE_ID and WORKSPACE_VERSION first')
}

const response = await fetch(
  `https://regex101.com/api/workspace/${workspaceId}/${workspaceVersion}`
)

if (!response.ok) {
  throw new Error(`regex101 returned ${response.status}: ${await response.text()}`)
}

console.log(await response.json())

import os

import requests

workspace_id = os.environ["WORKSPACE_ID"]
workspace_version = os.environ["WORKSPACE_VERSION"]

response = requests.get(
    f"https://regex101.com/api/workspace/{workspace_id}/{workspace_version}",
    timeout=30,
)
response.raise_for_status()

print(response.json())

This illustrative response omits fields from the full response:

{
  "permalinkFragment": "AbC123",
  "version": 1,
  "preferredEditorMode": "match",
  "regex": "regex\\d+",
  "testStrings": [
    {
      "name": null,
      "value": "regex101",
      "disabled": false
    }
  ],
  "flags": "g",
  "delimiter": "/",
  "flavor": "pcre2",
  "isPrivate": false,
  "isEditable": true,
  "isOwner": false
}

The full response also contains editor data, permissions, tags, unit tests, and substitution data.

Save a workspace

POST /api/workspace creates a workspace. Add permalinkFragment to the request body to save a new version of an existing workspace. You must have permission to edit that workspace.

Send the complete workspace data when adding a version. This operation is not a partial update.

The regular workspace schema requires regex, testStrings, substitution, unitTests, flags, delimiter, and flavor. The optional extraction field contains the extraction template, or null when unused.

Use null for unused substitution fields and [] for no unit tests. Each test string requires name, value, and disabled.

More than two test strings requires Pro on regex101.com. A self-hosted deployment needs the multiple-test-strings entitlement.

Substitution pipeline saves require editorMode: "substitution-pipeline" and the pipeline schema. They require Pro or the Substitution Pipeline entitlement.

The examples below create public workspaces owned by the signed-in account. To create a private workspace, add saveMode: "private". They require REGEX101_TOKEN. To create an anonymous workspace, omit the Authorization header. Anonymous workspaces are controlled through the delete codes returned by the API.

cURL
Node.js
Python

: "${REGEX101_TOKEN:?Set REGEX101_TOKEN through your credential configuration}"
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $REGEX101_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "regex": "regex\\d+",
    "testStrings": [
      {
        "name": null,
        "value": "Try regex101 and regex42",
        "disabled": false
      }
    ],
    "substitution": null,
    "extraction": null,
    "unitTests": [],
    "flags": "g",
    "delimiter": "/",
    "flavor": "pcre2"
  }' \
  "https://regex101.com/api/workspace"

const token = process.env.REGEX101_TOKEN
if (!token) throw new Error('REGEX101_TOKEN is required')

const response = await fetch('https://regex101.com/api/workspace', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    regex: 'regex\\d+',
    testStrings: [
      {
        name: null,
        value: 'Try regex101 and regex42',
        disabled: false,
      },
    ],
    substitution: null,
    extraction: null,
    unitTests: [],
    flags: 'g',
    delimiter: '/',
    flavor: 'pcre2',
  }),
})

if (!response.ok) {
  throw new Error(`regex101 returned ${response.status}: ${await response.text()}`)
}

console.log(await response.json())

import os

import requests

token = os.environ["REGEX101_TOKEN"]

response = requests.post(
    "https://regex101.com/api/workspace",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "regex": r"regex\d+",
        "testStrings": [
            {
                "name": None,
                "value": "Try regex101 and regex42",
                "disabled": False,
            }
        ],
        "substitution": None,
        "extraction": None,
        "unitTests": [],
        "flags": "g",
        "delimiter": "/",
        "flavor": "pcre2",
    },
    timeout=30,
)
response.raise_for_status()

print(response.json())

A successful save returns HTTP 201. This illustrative response shows the permalink fields and delete-code names:

{
  "permalinkFragment": "AbC123",
  "permalinkVersionDeleteCode": "<version-delete-code>",
  "permalinkDeleteCode": "<workspace-delete-code>",
  "version": 1,
  "isLibraryEntry": false
}

Store delete codes securely. They authorize deletion. Do not include them in shared workspace links.

Use the returned fragment and version to construct /r/{permalinkFragment}/{version}. Keep the version when you need a stable link to that saved revision.

Save mode

Set the optional saveMode field to choose the new workspace's privacy and editing permissions. Omitting it creates a public workspace.

Value	Effect when creating a workspace
`public`	Create a public workspace; this is the default.
`locked`	Create a public workspace that only its owner can edit.
`private`	Create a private workspace.

Creating a locked or private workspace requires sign-in. An anonymous request with either value returns 401.

The field applies to regular workspace and substitution pipeline creation. It does not change privacy or editing permissions when you add a version to an existing workspace.

Delete codes and account deletion

Delete-code requests send a JSON body containing deleteCode. Use the workspace code for workspace deletion and the version code for version deletion.

These are separate from account-owned deletion routes:

Method and path	Authorization
`DELETE /api/workspace`	Workspace delete code in the body.
`DELETE /api/workspace/{version}`	Version delete code in the body.
`DELETE /api/user/{permalinkFragment}`	Signed-in account that owns the workspace.
`DELETE /api/user/{permalinkFragment}/{version}`	Signed-in account that owns the workspace.

Successful deletion returns 204 without a response body. Deleting the last version also deletes the workspace.

Deletion is permanent. Verify the target and retain any required copy before sending a delete request.

Errors

Error responses contain error and errorId. Schema validation errors can also contain validationError, validation, and validationContext.

Status	Common cause	Next action
`400`	Request does not match the schema.	Verify required fields, types, flags, and delimiters.
`401`	Missing required sign-in, or an invalid supplied bearer token.	Reauthenticate through the client.
`403`	Workspace permissions or feature access do not permit the operation.	Verify ownership, privacy, and plan or license access.
`404`	The requested resource or version does not exist.	Verify the fragment and version.
`413`	Request exceeds the deployed body limit.	Reduce the request size and verify deployment limits.
`5xx`	Server-side failure.	Retain the `errorId` for support.

Keep credentials and private workspace content out of error logs. For support, provide the status and errorId with a description of the operation.

If a save request loses its connection, verify whether it succeeded before sending another save.

Routes​

Authentication​

Example prerequisites​

Get a workspace​

Save a workspace​

Save mode​

Delete codes and account deletion​

Errors​