Skip to content
Docs/HTTP API
REDAX / API

HTTP API

Put Redax directly in front of your LLM call. Send text in, receive safe text plus the evidence you need to operate the boundary.

WHYKeep raw customer text outside the model boundary.
WHATA local API that detects, replaces, and records safely.
HOWRun it, send text, pass only returned text onward.
Why this endpoint exists

An LLM provider should never be the first system that sees customer text. /v1/redact gives your application one explicit boundary: the raw request enters Redax, sensitive spans are replaced locally, and only the safe result continues to the model.

The request path

Call this endpoint at the boundary where text leaves your controlled system. The steps are intentionally visible so a developer can reason about privacy, correctness, and operations separately.

1
Send
Your application sends text and an optional policy.
2
Detect
Regex and/or a local NER model find candidate spans.
3
Replace
Redax applies the policy and creates typed placeholders.
4
Continue
Your model receives only the redacted text.

Start with one request

The smallest useful integration is one JSON request. Authentication is optional in local development and enabled with X-API-Key in a deployed environment.

curl -s -X POST http://localhost:8000/v1/redact \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: checkout-8421' \
  -d '{"text":"Email me at alice@example.com"}'

Use X-Request-ID to correlate the response, application logs, traces, and audit event. Redax echoes it back.

Request fields

textrequired

The string to inspect. The maximum is controlled by REDAX_MAX_TEXT_CHARS.

entity_typesoptional

Limit detection on the policy redactor path; at most 128 non-empty labels of 128 characters each. Do not combine with use_pipeline.

policyoptional

Inline policy override. It is bounded and validated before execution: malformed or unsupported policies return 422 and never become an empty pass-through policy. Omit it to use REDAX_DEFAULT_POLICY.

use_pipelineoptional

Selects the staged regex/model/consensus path with typed placeholders. It cannot be combined with policy or entity_types; that combination returns 422.

Response shape

The response serves two consumers: the next LLM call needs text, while your application and operators need spans, a keyed digest, and pipeline state. The audit log records metadata, never the original value.

{
  "text": "Email me at [EMAIL_0000]",
  "spans": [{"start": 12, "end": 29, "type": "EMAIL", "confidence": 1.0}],
  "relex_map": {},
  "used_pipeline": false,
  "used_fallback": false,
  "digest": "8f1d2c..."
}

Choose the endpoint for the workload

All redaction transports use REDAX_DEFAULT_POLICY when no explicit policy or entity-type selection is supplied. That keeps one policy contract across synchronous, batch, stream, and job requests.

/v1/detect
Diagnostics

Return original text plus validated spans; never forward this response as redacted output.

/v1/redact
One request

Interactive prompts, chat messages, and synchronous transformed output.

/v1/redact/batch
Many requests

Up to 1,000 items in parallel under one overall timeout.

/v1/redact/stream
Long documents

Server-sent events for chunked processing without waiting for the whole document.

/v1/jobs
Async work

Queue large jobs, poll by ID, and keep the request thread responsive.

Errors and safe retries

Errors use RFC 7807 application/problem+json so clients can branch on stable status and type fields. Expect 413 for oversized input, 422 for invalid JSON, 429 for rate limits, 503 when the service is not ready, and 504 for a timeout.

Send an Idempotency-Key with retryable POST requests. Redis leases the key before redaction, so concurrent replicas cannot silently perform unrelated work under one key. The same fingerprint replays the safe result; a different body returns 409, and an in-flight duplicate returns 409 until the lease expires or completes.

Next step

Once the single request works, read the integration guide to choose the boundaries that fit your threat model, then use the deployment checklist before exposing it to production traffic.

Read integration →Production checklist