API

Quick start

1. Sign in (Login / Register) and create an API key under Setup → API keys. 2. Send a text:

curl https://api.aidataveil.eu/v1/anonymize \
  -H "Authorization: Bearer $VEIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, I am Anna Schmidt from Berlin, anna@example.com.", "lang": "en"}'

The answer contains the veiled text and the list of what was replaced:

{
  "text": "Hello, I am [PERSON_1] from [LOCATION_1], [EMAIL_1].",
  "replacements": [
    { "type": "PERSON",   "original": "Anna Schmidt",     "replacement": "[PERSON_1]" },
    { "type": "LOCATION", "original": "Berlin",           "replacement": "[LOCATION_1]" },
    { "type": "EMAIL",    "original": "anna@example.com", "replacement": "[EMAIL_1]" }
  ],
  "infos": {},
  "usage": { "chars": 55, "tokens": 18, "size_class": "S", "weight": 1, "billed_tokens": 18 },
  "meta": { "lang": "en", "mode": "technical", "total_ms": 240 }
}

Authentication

Base address: https://api.aidataveil.eu. Send your key in the header Authorization: Bearer veil_…. Keep keys secret. An account can have up to 5 keys, and you can delete a key at any time.

Request: POST /v1/anonymize

Response

Short and long texts

Texts up to 1,000 tokens (about 3,500 characters, a long email) are answered immediately. Longer texts are accepted and processed in the background; you fetch the result later. Short requests are not delayed by this: they always go first.

HTTP/1.1 202 Accepted
{
  "request_id": "6549e33e1121a934ac0ece670c8b5017",
  "status": "queued",
  "tokens": 15900,
  "size_class": "XL",
  "result_url": "/v1/requests/6549e33e1121a934ac0ece670c8b5017",
  "poll_after_seconds": 100
}

Fetch the result with GET result_url. The status is queued, processing, done or failed. A finished result comes in blocks of up to 10,000 characters, each with a link to the next one:

GET /v1/requests/6549e33e1121a934ac0ece670c8b5017
{
  "request_id": "6549e33e1121a934ac0ece670c8b5017",
  "status": "done",
  "block": 1,
  "blocks": 7,
  "next_url": "/v1/requests/6549e33e1121a934ac0ece670c8b5017?block=2",
  "next_is_confirmation": false,
  "text": "…first 10,000 characters, veiled…",
  "replacements": [ … only those used in this block … ],
  "infos": {}, "usage": { … }, "meta": { … }
}

• Placeholders are the same in all blocks: [PERSON_1] always means the same term. Each block lists the replacements it contains.
• infos, usage and meta are in the first block.
• Fetching block N+1 confirms that block N has arrived; block N is then released (410 block_released if you ask again). If a connection drops, simply request the same block again.
• The next_url of the last block (next_is_confirmation: true) confirms receipt and deletes the request. Without confirmation the result is deleted 60 minutes after the last block was fetched, after 24 hours at the latest. DELETE /v1/requests/{id} deletes at once.
• "async": true processes even short texts in the background (same price). "async": false demands an immediate answer; a text that is too long is rejected with 413 too_large_for_immediate.

A complete example in Python:

import os, time, requests

API = "https://api.aidataveil.eu"
H = {"Authorization": "Bearer " + os.environ["VEIL_KEY"]}

def anonymize(text, lang="de"):
    r = requests.post(API + "/v1/anonymize", headers=H, json={"text": text, "lang": lang})
    r.raise_for_status()
    if r.status_code == 200:                      # short text: the answer is here
        return r.json()["text"]
    url = API + r.json()["result_url"]            # 202: processed in the background
    while (block := requests.get(url, headers=H).json())["status"] in ("queued", "processing"):
        time.sleep(10)
    if block["status"] == "failed":
        raise RuntimeError(block["error"])
    parts = []
    while True:
        parts.append(block["text"])
        if block["next_is_confirmation"]:         # last block: confirm, the data is deleted
            requests.get(API + block["next_url"], headers=H)
            return "".join(parts)
        block = requests.get(API + block["next_url"], headers=H).json()

Rule sets

Under Setup → Rule sets you collect your own terms: words that are always replaced (project names, customer numbers) and words that are never replaced (your company, products). Assign a rule set to a key as its default, or name it per request with ruleset.

Besides terms, a rule set can contain fields: values of a fixed shape such as an order number. You create a field in Setup → Rule sets by pasting a sample text and clicking the value; we build the pattern for you, you give it a technical name such as Ordernumber. Every match is returned under infos.Ordernumber and, if you like, replaced in the text. Fields of the rule set and rules of the request work together.

Tokens, limits and billing

• Only tokens are billed. A token is a small piece of a word, roughly 3 to 4 characters. Every answer shows the size in usage.
• POST /v1/tokens with {"text": "…"} returns the token count and whether the text would be answered immediately. It does not process the text and costs nothing.
• The monthly token limit belongs to the account and counts for all keys together; creating more keys does not raise it.
• By default the API stops at the limit and answers with 429 quota_exceeded until the next month or until the plan is upgraded. Continuing and billing the extra tokens afterwards will come with the paid plans; we set it up for you.
• Owners get an email when the forecast for the month turns yellow or red, if they switched this on in their profile.

Errors

Data handling

• Texts are processed on our own servers in Europe, with models that run locally. No external AI service is involved and nothing is used for training.
• Immediate requests are processed in memory. We store only counts (requests, tokens), never the text.
• Background requests are the one exception: the text is stored encrypted until it has been processed and then deleted; the result stays encrypted until you have fetched it (released block by block), at most 24 hours.