Native PII API v2

Detect, protect, and restore personal data in text, tables, JSON, transcripts, images, and documents with one contract.

Start with the capabilities

Read the capabilities once at start. They list the models, languages, input kinds, tiers and limits of your deployment.

export SHINRAI_API_KEY=shr_live_...

curl -s https://api.shinrai.innovius.io/v2/capabilities -H "Authorization: Bearer $SHINRAI_API_KEY"

Send any input kind

A plain text needs no wrapper. For a text file or an image, send the file itself as the request body and put options in the query string.

curl -s https://api.shinrai.innovius.io/v2/detect -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" -d '{"text": "Anna Weber, anna.weber@example.org, IBAN DE89 3704 0044 0532 0130 00"}'

curl 'https://azure.api.shinrai.innovius.io/language/:analyze-text?api-version=2023-04-01' \
  -H "Ocp-Apim-Subscription-Key: $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"PiiEntityRecognition","analysisInput":{"documents":[{"id":"1","language":"en","text":"Anna Weber, anna.weber@example.org, IBAN DE89 3704 0044 0532 0130 00"}]},"parameters":{"modelVersion":"latest","stringIndexType":"Utf16CodeUnit"}}'

# Once: create SigV4 credentials with your ShinrAI key
# curl -X POST https://aws.api.shinrai.innovius.io/providers/aws/credentials -H "Authorization: Bearer $SHINRAI_API_KEY"
import boto3, os

client = boto3.client(
    "comprehend",
    region_name="eu-central-1",
    endpoint_url="https://aws.api.shinrai.innovius.io",
    aws_access_key_id=os.environ["SHINRAI_AWS_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["SHINRAI_AWS_SECRET_ACCESS_KEY"],
)
print(client.detect_pii_entities(Text="Anna Weber, anna.weber@example.org, IBAN DE89 3704 0044 0532 0130 00", LanguageCode="en"))

curl 'https://google.api.shinrai.innovius.io/v2/projects/my-project/locations/global/content:inspect' \
  -H "x-goog-api-key: $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item":{"value":"Anna Weber, anna.weber@example.org, IBAN DE89 3704 0044 0532 0130 00"},"inspectConfig":{"includeQuote":true}}'

curl -s https://api.shinrai.innovius.io/v2/protect?preset=label -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: text/plain" -H "Accept: text/plain" --data-binary @letter.txt

Choose how to protect

A preset sets one policy for all types. Rules set an action per type.

• Pseudonymize writes realistic surrogates that you can restore.
• Partial keeps what does not identify: the e-mail domain, the phone country prefix, the last four digits of a card or account, the year of a date.
• Generalize writes a phrase for the kind of name, place or organisation, in the input language.
• Partial and generalize are one-way.

curl -s https://api.shinrai.innovius.io/v2/protect -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Anna Weber aus Biberach, anna@example.org, Karte 4111 1111 1111 1111", "language": "de",
       "policy": {"default": {"action": "generalize"}, "rules": [{"types": ["EMAIL", "CREDIT_CARD"], "action": "partial"}]}}'

Control detection

• Set a confidence floor for all types, per type or per language.
• Include or exclude types by their canonical names or by the names of Google, AWS, Azure or Presidio.
• Exclude values that must never be reported, such as your company name, or add values of your own.
• Ask for annotations: years, amounts, legal references and bias terms. Protect never changes them.
• Ask for the linkage risk: an estimate of how likely an input singles out a person. It is a heuristic, not a count.

Restore and keep one map

Ask for the mapping when you must restore an answer later. The mapping contains the original values. Store it as sensitive application data and keep it out of model prompts.

curl -s https://api.shinrai.innovius.io/v2/protect -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Anna Weber lives in Darmstadt.", "policy": {"preset": "pseudonymize"}, "output": {"include": ["entities", "mapping"]}}'

# Azure returns the masked text as redactedText.
curl 'https://azure.api.shinrai.innovius.io/language/:analyze-text?api-version=2023-04-01' \
  -H "Ocp-Apim-Subscription-Key: $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"PiiEntityRecognition","analysisInput":{"documents":[{"id":"1","language":"en","text":"Anna Weber lives in Darmstadt."}]},"parameters":{"modelVersion":"latest","stringIndexType":"Utf16CodeUnit"}}'

curl 'https://google.api.shinrai.innovius.io/v2/projects/my-project/locations/global/content:deidentify' \
  -H "x-goog-api-key: $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item":{"value":"Anna Weber lives in Darmstadt."},"deidentifyConfig":{"infoTypeTransformations":{"transformations":[{"primitiveTransformation":{"replaceWithInfoTypeConfig":{}}}]}}}'

curl -s https://api.shinrai.innovius.io/v2/restore -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mapping": {"known": [{"original": "Anna Weber", "replacement": "Julia Brandt"}]}, "inputs": [{"id": "1", "text": "Julia Brandt replied."}]}'

• Within one request, a value keeps one surrogate.
• The next request draws new surrogates, so repeated requests cannot map surrogates back to originals.
• For the same surrogates across requests, use a session or send the earlier pairs as known mappings.
• Account-wide consistency is available as an option. It is weaker: anyone with the key can then build a table of originals by repetition.
• Other customers always get different surrogates.

A session holds one map on the server for at most 24 hours. The map is stored encrypted, and only your key can read it.

SESSION=$(curl -s -X POST https://api.shinrai.innovius.io/v2/sessions -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" -d '{"ttl_s": 3600}' | python3 -c 'import sys, json; print(json.load(sys.stdin)["id"])')
curl -s https://api.shinrai.innovius.io/v2/protect -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" -d '{"text": "Anna Weber called.", "mapping": {"session": "'$SESSION'"}}'
curl -s https://api.shinrai.innovius.io/v2/sessions/$SESSION/mapping -H "Authorization: Bearer $SHINRAI_API_KEY"

Protect screenshots and scans

• OCR reads every language the model serves. Send the language for Arabic, Hebrew, Japanese and Korean images.
• Every entity comes back with pixel boxes, one per text line or one per word.
• Protect returns the image with the regions filled.
• The realtime tier takes one image per request, up to 4.2 megapixels and 3 MiB.

curl -s "https://api.shinrai.innovius.io/v2/detect?language=de" -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: image/png" --data-binary @screenshot.png

curl -s https://api.shinrai.innovius.io/v2/protect -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: image/png" -H "Accept: image/png" --data-binary @screenshot.png -o redacted.png

Run large batches and documents as jobs

Use a job when the work is too large for one request: many texts, or a PDF or Word file. A job runs in the background at the batch weight and keeps its results for 24 hours. Jobs are in beta.

1. Upload a JSONL file with one input per line, or a PDF or DOCX file.
2. Start the job with the upload ID.
3. Poll the job and download the artifacts.

{"custom_id": "row-1", "text": "Anna Schmidt, anna@example.com"}
{"custom_id": "row-2", "text": "Call +49 30 1234567", "language": "de"}
{"custom_id": "row-3", "input": {"kind": "table", "columns": [{"name": "email"}], "rows": [["max@example.org"]]}}

curl -s https://api.shinrai.innovius.io/v2/uploads \
  -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @rows.jsonl

curl -s https://api.shinrai.innovius.io/v2/jobs \
  -H "Authorization: Bearer $SHINRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rows-2026-09-28" \
  -d '{"kind": "text_batch",
       "inputs": [{"kind": "file", "source": {"upload": "up_..."}}],
       "output": {"artifacts": ["protected", "entities"]}}'

curl -s https://api.shinrai.innovius.io/v2/jobs/$JOB -H "Authorization: Bearer $SHINRAI_API_KEY"

A document job protects the text of the document. The redacted PDF and its word boxes come in a later release.

Tiers, retries and usage

• Send an Idempotency-Key header to retry safely. A repeat with the same key and body is charged once.
• Restore, sessions, capabilities, types and usage are free.
• Failed calls are not charged.

curl -s https://api.shinrai.innovius.io/v2/usage -H "Authorization: Bearer $SHINRAI_API_KEY"

Coming next

Audio input and streaming are planned for the native API v2. They are not available yet.

Reference

• Full v2 reference (Markdown)
• API explorer (Swagger)
• OpenAPI 3.1 for v2
• OpenAPI 3.1 for all APIs