# Quickstart

RegexSolver is an API that treats a regular expression as the **set of strings it matches**. Instead of testing one string at a time, you ask questions about whole patterns and get exact answers.

## Common uses

* **Verify a rule change.** Replacing a rule by another one: does the new rule still accept every values the old one did? A **subset** check answers this for the whole language rather than for sampled examples.
* **Detect overlapping patterns.** Two routes, two permission rules, two parser branches. **Intersect** them and test whether the result is **empty**. Empty is a proof that no string can ever match both.
* **Generate data that fits a spec.** You already wrote the format as a regex, so ask for strings that match it and use them as fixtures.

The same idea covers subtracting one pattern from another to see what a rule rejects, counting how many strings a pattern accepts, and checking whether two differently-written patterns mean the same thing.

Every operation runs on RegexSolver's servers, through a client library for Java, JavaScript or Python.

## Get an API token

Every request to the API is authenticated with an API token.

<Stepper>

1. **Create an account:** Sign up on the [RegexSolver Console](https://console.regexsolver.com/).
2. **Create a token:** Open the **API Tokens** page from the sidebar and click **Create token**. Enter a label that describes where the token will be used (for example `CI Pipeline` or `Production-01`), optionally pick an expiration date, and click **Generate token**.
3. **Copy it:** The token is shown only once. Copy it and store it securely. Never commit it to a repository or expose it in client-side code.

</Stepper>

## Make your first request

Two patterns describe the same IDs from opposite sides: your service accepts `[A-Z]{3}-[0-9]{4}`, and an upstream system sends `(ORD|INV)-[0-9]+`. Intersecting them answers which IDs actually get through.

<CodeTabs defaultValue="java">
<CodeTabs.Tab value="java" label="Java">
**Requirements:** Java >= 11

Install our [Java API client](https://github.com/RegexSolver/regexsolver-java) by adding one of the following lines to the appropriate file in your Gradle or Maven project:

**Gradle:**
```groovy
implementation "com.regexsolver.api:RegexSolver:1.1.0"
```

**Maven:**
```xml
<dependency>
    <groupId>com.regexsolver.api</groupId>
    <artifactId>RegexSolver</artifactId>
    <version>1.1.0</version>
</dependency>
```

Then create a new environment variable called `REGEXSOLVER_API_TOKEN` that contains your API token.
You can now run the following example:
```java
import com.regexsolver.api.RegexSolverClient;
import com.regexsolver.api.Term;
import com.regexsolver.api.exceptions.ApiException;

public class Main {
    public static void main(String[] args) throws ApiException {
        RegexSolverClient client = RegexSolverClient.builder()
                .apiToken(System.getenv("REGEXSOLVER_API_TOKEN"))
                .build();

        Term rule = Term.regex("[A-Z]{3}-[0-9]{4}");
        Term upstream = Term.regex("(ORD|INV)-[0-9]+");

        Term accepted = client.intersection(rule, upstream);

        System.out.println(client.getPattern(accepted));
    }
}
```

If your token is set correctly, the following pattern is printed:
```
(INV|ORD)\-[0-9]{4}
```
</CodeTabs.Tab>

<CodeTabs.Tab value="javascript" label="JavaScript">
**Requirements:** Node.js >= 18

Install our [JavaScript API client](https://github.com/RegexSolver/regexsolver-js) by running:

```shell
npm i regexsolver
```

Then create a new environment variable called `REGEXSOLVER_API_TOKEN` that contains your API token.

You can now run the following example:
```javascript
import { RegexSolverClient, Term } from 'regexsolver';

const client = new RegexSolverClient({ apiToken: process.env.REGEXSOLVER_API_TOKEN });

const rule = Term.regex("[A-Z]{3}-[0-9]{4}");
const upstream = Term.regex("(ORD|INV)-[0-9]+");

const accepted = await client.intersection(rule, upstream);

console.log(await client.getPattern(accepted));
```

If your token is set correctly, the following pattern is printed:
```
(INV|ORD)\-[0-9]{4}
```
</CodeTabs.Tab>

<CodeTabs.Tab value="python" label="Python">
**Requirements:** Python >= 3.10

Install our [Python API client](https://github.com/RegexSolver/regexsolver-python) by running:

```shell
pip install --upgrade regexsolver
```

Then create a new environment variable called `REGEXSOLVER_API_TOKEN` that contains your API token.

You can now run the following example:
```python
import os
from regexsolver import RegexSolverClient, Term

client = RegexSolverClient(api_token=os.getenv("REGEXSOLVER_API_TOKEN"))

rule = Term.regex(r"[A-Z]{3}-[0-9]{4}")
upstream = Term.regex(r"(ORD|INV)-[0-9]+")

accepted = client.intersection(rule, upstream)

print(client.get_pattern(accepted))
```

If your token is set correctly, the following pattern is printed:
```
(INV|ORD)\-[0-9]{4}
```
</CodeTabs.Tab>

</CodeTabs>

The answer is the IDs the upstream can send and your service will accept: an `ORD` or `INV` prefix followed by exactly four digits. Neither input pattern states that on its own, and no amount of testing individual IDs would have proven it.

Two points from that example:

* **`intersection` returned a Term.** Every operation takes Terms and returns Terms, so the result is a valid input to the next call, and `getPattern` is the separate step that turns one into readable text. [Term's Format](/core-concepts/terms-format) covers why.
* **`INV-12345` is not in the result**, even though its first four digits look like a match for `[A-Z]{3}-[0-9]{4}`. A pattern here has to match the whole string, which is the subject of the next section.

## Implicit anchoring

**Patterns are implicitly anchored.** A pattern always has to match the string from beginning to end, as though it were wrapped in `^...$`.

So `abc` matches `"abc"` and does **not** match `"xabc"` or `"abcx"`. There are no search semantics here. To express "contains abc", write `.*abc.*`.

<Callout type="caution">
A few other regex features behave differently here, because RegexSolver works on **pure regular languages**: lookaround and backreferences are not supported, and `.` matches newlines. [Term's Format](/core-concepts/terms-format#regex-regular-expression) has the full list.
</Callout>

## Plan limits

During early access every account is on the **Free plan**. Two of its limits apply to every call:

* **5 Terms** per operation. The clients split longer lists into several requests for you.
* **500 ms** of server-side compute per operation, applied unless you ask for less.

[Plans and Pricing](/plans-pricing) lists the rest, including the monthly quota and the rate limit.

## Next steps

* [All Operations](/operations) is the one-page index: every operation, its description, and its method name in each language.
* [Sync and Async Clients](/sync-async) covers the synchronous and asynchronous clients.
* [Core Concepts](/core-concepts/terms-format) starts with the Term, the data type every operation works on, then walks through each operation with examples.
* [Error Handling](/error-handling) shows how errors are organized and how to catch them.
* The [API Reference](/api) documents every endpoint directly.