# Quickstart | Chersus

Documentation

# Quickstart

Make your first Chersus run in under five minutes: get an API key, send a POST /v1/run request, and read the JSON result.

Last updated 2026-09-03

Chersus is one API surface: one URL, one header, and a JSON body that declares an input and a pipeline. That is the whole learning curve. Everything below takes about five minutes. [See all services](/en/services/).

## Get an API key

Create a free account and copy your key from the dashboard. Keys look like `chrs_live_...`, and you see yours exactly once, at creation. Store it somewhere safe now.

```
# Store it in your environment, not in your code
export CHERSUS_KEY=chrs_live_YOUR_KEY
```

## Make your first run

Every request goes to `POST /v1/run`. The body carries the input and a pipeline of one or more steps. Here is a run that redacts the PII from a sentence:

```
curl -X POST https://api.chersus.com/v1/run \
-H "Authorization: Bearer $CHERSUS_KEY" \
-H "Content-Type: application/json" \
-d '{
  "input": {
    "type": "text",
    "value": "Contact Jane Doe at jane.doe@example.com about invoice #4821."
  },
  "pipeline": [
    { "id": "redact", "service": "governance.pii.redact" }
  ]
}'
```

```
const res = await fetch("https://api.chersus.com/v1/run", {
method: "POST",
headers: {
  Authorization: "Bearer " + process.env.CHERSUS_KEY,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  input: {
    type: "text",
    value: "Contact Jane Doe at jane.doe@example.com about invoice #4821.",
  },
  pipeline: [{ id: "redact", service: "governance.pii.redact" }],
}),
});

const data = await res.json();
```

```
import os

import requests

res = requests.post(
  "https://api.chersus.com/v1/run",
  headers={"Authorization": "Bearer " + os.environ["CHERSUS_KEY"]},
  json={
      "input": {
          "type": "text",
          "value": "Contact Jane Doe at jane.doe@example.com about invoice #4821.",
      },
      "pipeline": [{"id": "redact", "service": "governance.pii.redact"}],
  },
)

data = res.json()
```

## Read the result

The response tells you what happened, what it cost, and exactly what ran:

```
{
  "trace_id": "chs_01J9X4Q7K2M8N3P5R6T7V8W9X0",
  "status": "completed",
  "output": {
    "type": "text",
    "value": "Contact [REDACTED] at [REDACTED] about invoice #4821."
  },
  "results": {
    "redact": { "kind": "transform", "status": "ok", "changes": 2 }
  },
  "usage": {
    "billed": [
      { "unit": "characters", "quantity": 61, "steps": ["redact"] }
    ]
  },
  "audit": {
    "region": "eu-nl-1",
    "retention": "none",
    "total_ms": 26
  }
}
```

Three things to know:

 - **Services come in three kinds.** A transform rewrites the payload. A classify attaches a `verdict` and a `score`. An extract emits JSON in `data`. Handle the three kinds once, and you can call any service, including ones that do not exist yet.
 - **The audit trace is always there.** It records each step’s model, version, timing, and SHA-256 content hashes. That is enough to prove what ran, while Chersus stores none of the content.
 - **Billing travels with the response.** `usage.billed` lists one entry per executed step, with the characters that step processed. Every step bills, so a two-step run costs twice a one-step run on the same input.

## Explore the directory

The [services directory](/en/services/) lists every service, each with a request and response example. When one step is not enough, the [chaining guide](/en/docs/chaining/) shows how to run several in a single request.

Your first 50K characters each month are free, roughly a hundred support tickets. No payment method needed to [get your key](/en/signup/).