Referenz der API für Anwendungen
Die API für Anwendungen eines Latet-Servers beantwortet vier Operationen unter
https://<Ihr Server>/_latet/apps/v1/. Dies ist Version 1: Eine Änderung, mit der ein dafür
geschriebenes Programm nicht mehr funktionieren würde, kommt als v2, daneben. Die OpenAPI-Beschreibung
sagt dasselbe für Tools, die einen Client erzeugen; Python-Programme können latet-client
verwenden (Logs, RAG). Ein Latet-Server liefert
die Beschreibung seiner eigenen Version auch selbst aus, ohne Token, unter
https://<Ihr Server>/_latet/docs/apps-api.openapi.json.
Authentifizierung
Abschnitt betitelt „Authentifizierung“Jeder Aufruf trägt das Token eines API-Schlüssels in einem einzigen Header:
Authorization: Bearer latet_key_...Ein Token ist latet_key_ gefolgt von 43 Zeichen, und der Administrator erzeugt es
(latet server keys add, keys add-token). Jede Operation braucht ihre eigene Berechtigung: scan,
mask (das scan einschließt), unmask oder forget (das keine andere einschließt und das das erste
Token eines Schlüssels nicht hat). Der Server lehnt ab:
- mit 401 und
WWW-Authenticate: Bearereinen Aufruf ohneAuthorization-Header, mit zweien, mit einem anderen Schema alsBeareroder mit einem Token, das er nicht kennt (widerrufen, rotiert, von einem deaktivierten oder entfernten Schlüssel); - mit 403 das Rechnertoken einer Person, ein Token ohne die Berechtigung der Operation und jede
Anfrage, die einen Header
OriginoderSec-Fetch-Siteträgt, wie die eines Browsers: Die API ist für Programme, nie für eine Webseite.
Tokens, die der Server ablehnt, zählen für die Adresse, von der sie kommen, wie auf jeder Route des Servers: Über der Grenze antwortet er mit 429. Rufen Sie den Server über HTTPS auf; sonst gehen das Token und die Texte im Klartext über das Netz.
Anfragen
Abschnitt betitelt „Anfragen“| Operation | Pfad | Berechtigung | Body |
|---|---|---|---|
| Analysieren | POST /_latet/apps/v1/scan |
scan |
{"texts": [...], "kind": "prose"} |
| Maskieren | POST /_latet/apps/v1/mask |
mask |
{"texts": [...], "kind": "prose"} |
| Wiederherstellen | POST /_latet/apps/v1/unmask |
unmask |
{"texts": [...]} |
| Vergessen | POST /_latet/apps/v1/forget |
forget |
{"values": [...]} |
textsist eine Liste von 1 bis 1.000 Zeichenketten, die in derselben Reihenfolge beantwortet werden. Ein leerer Text kommt unverändert zurück, ohne Funde und mitrestored: 0.valuesist eine Liste von 1 bis 1.000 Zeichenketten, die Werte, die aus dem Tresor des Schlüssels entfernt werden sollen, jeder genau so gesucht, wie er geschrieben ist (Werte vergessen).kindistprose(Text, den Menschen geschrieben haben, der Standard) oderdata(Logs, Datensätze, die Ausgabe eines Programms); siehe Prosa und Daten.nulloder ein anderes Wort wird abgelehnt. Beim Wiederherstellen gibt es keinkind.- Der Body ist ein JSON-Objekt von höchstens
apps_request_mbdes Servers (8 MiB, wenn seine Einstellungen nichts anderes festlegen, nie mehr als seinmax_request_mb).
Analysieren und Wiederherstellen mit curl, das Token über die Standardeingabe übergeben wie beim ersten Aufruf, der maskiert; die Antworten stehen weiter unten:
printf 'Authorization: Bearer %s' "$(cat shop.key)" | curl -sS -H @- -H "Content-Type: application/json" \ -d '{"texts": ["Bitte erstatten Sie die Bestellung von mario.rossi@acme.it auf IT60X0542811101000000123456."]}' \ https://latet.acme.lan/_latet/apps/v1/scanprintf 'Authorization: Bearer %s' "$(cat shop.key)" | curl -sS -H @- -H "Content-Type: application/json" \ -d '{"texts": ["Bitte erstatten Sie die Bestellung von tommaso.gallo@margie-6e5a.example auf IT17F3945471087320356678487."]}' \ https://latet.acme.lan/_latet/apps/v1/unmaskAntworten
Abschnitt betitelt „Antworten“Jede Antwort von Analysieren, Maskieren und Wiederherstellen ist ein JSON-Objekt, dessen results für
jeden gesendeten Text einen Eintrag enthalten, in derselben Reihenfolge; ein Vergessen antwortet mit
zwei Zahlen.
Analysieren sagt, wo die Werte im gesendeten Text stehen, und behält nichts:
{"results": [{"findings": [{"type": "EMAIL", "class": "pii", "start": 39, "end": 58}, {"type": "IBAN", "class": "pii", "start": 63, "end": 90}], "counts": {"EMAIL": 1, "IBAN": 1}}]}Maskieren gibt jeden Text mit den Ersatzwerten des Schlüssels zurück, und wo sie im zurückgegebenen Text stehen:
{"results": [{"text": "Bitte erstatten Sie die Bestellung von tommaso.gallo@margie-6e5a.example auf IT17F3945471087320356678487.", "replacements": [{"type": "EMAIL", "class": "pii", "start": 39, "end": 72}, {"type": "IBAN", "class": "pii", "start": 77, "end": 104}], "counts": {"EMAIL": 1, "IBAN": 1}}, {"blocked": "the local reviewer could not read the user text (it took longer than the 30 seconds an application's call waits for it, which llm_review.budget_ms changes), so it was not sent"}], "degraded": ["llm-review"]}- Ein Ergebnis mit
blockedund ohnetextist ein Text, den Latet nicht beantwortet: Der lokale Prüfer hat ihn gestoppt, seine Prüfung ist gescheitert undllm_review.on_failuredes Schlüssels iststop, oder der Dump-Schutz hat ihn zurückgehalten. Der Grund, auf Englisch, nennt keinen Wert. degraded, nur vorhanden, wenn im Aufruf etwas eingeschränkt lief, nennt, was es betraf: einen Detektor, der einen Text nicht lesen konnte (etwaner), oderllm-review.
Wiederherstellen gibt jeden Text zurück, in dem jeder Ersatzwert aus dem Tresor des Schlüssels durch seinen Wert ersetzt ist, und wie viele verschiedene Werte es wiederhergestellt hat:
{"results": [{"text": "Bitte erstatten Sie die Bestellung von mario.rossi@acme.it auf IT60X0542811101000000123456.", "restored": 2}]}Vergessen sagt, wie viele der Werte der Tresor des Schlüssels enthielt, die jetzt mit ihren Ersatzwerten verschwunden sind, und wie viele er nicht enthielt; jeder Wert zählt einmal:
{"forgotten": 1, "unknown": 1}Positionen
Abschnitt betitelt „Positionen“start und end zählen Unicode-Codepunkte (end nicht eingeschlossen): In Python ist
text[start:end] der Wert. JavaScript, Java und C# zählen UTF-16-Einheiten, in denen ein Zeichen
jenseits der Basic Multilingual Plane, wie die meisten Emoji, zwei belegt. In
Schreiben Sie an 👩💻 mario.rossi@acme.it beginnt die Adresse bei 21 in Codepunkten und bei 23 in
UTF-16-Einheiten; in JavaScript liefert sie Array.from(text).slice(start, end).join("").
Typen und Klassen
Abschnitt betitelt „Typen und Klassen“type ist der Typ des Wertes: EMAIL, PHONE, IBAN, CREDIT_CARD, IP_ADDRESS und die anderen
der Detektoren, die Regel eines Geheimnisses oder der Typ eines Begriffs, Erkenners
oder einer Feldregel des Schlüssels. class ist die Familie dessen, was ihn gefunden hat: secret,
custom (die Begriffe und Erkenner des Schlüssels), identity, pii, ner (das Namensmodell),
llm (der lokale Prüfer) oder struct (der strikte Datenmodus).
Ein Fehler ist {"error": "<Worte>"}. Die Worte, auf Englisch, sind für Menschen: Sie zitieren nie
einen gesendeten Text, und die Ablehnungen am Eingang des Servers (Authentifizierung, Grenzen)
beginnen mit latet: . Entscheiden Sie nach dem Status.
| Status | Wann | Was tun |
|---|---|---|
| 400 | Der Body ist kein JSON-Objekt mit texts als Liste von 1 bis 1.000 Zeichenketten und, für Analysieren und Maskieren, einer Art (kind) prose oder data; beim Vergessen mit values als Liste von 1 bis 1.000 Zeichenketten. |
Den Aufruf korrigieren. |
| 401 | Kein Token, zwei Authorization-Header, ein anderes Schema oder ein Token, das der Server nicht kennt. |
Das Token prüfen; ein neues anfordern. |
| 403 | Dem Token fehlt die Berechtigung (this token lacks the mask permission), es ist das Token einer Person, oder eine Webseite hat die Anfrage gestellt. |
Ein Token mit der Berechtigung verwenden. |
| 404 | Ein anderer Pfad unter /_latet/apps/v1/. |
|
| 405 | Eine andere Methode als POST (Allow: POST). |
|
| 413 | Der Body ist größer als apps_request_mb. |
Weniger Texte pro Aufruf senden. |
| 422 | Analysieren, Maskieren und Wiederherstellen: Die Texte nennen mehr als 100.000 Werte oder Ersatzwerte des Tresors, mehr als ein Aufruf abwägen darf. Nichts wurde maskiert oder wiederhergestellt. | Weniger Texte pro Aufruf senden. |
| 429 | Zu viele abgelehnte Tokens von dieser Adresse, oder der Schlüssel hat requests_in_flight Anfragen an die API für Anwendungen auf dieser Instanz (16, wenn die Einstellungen nichts anderes festlegen). |
Retry-After abwarten, dann erneut versuchen. |
| 500 | Ein anderer Fehler; seine Worte nennen keinen Wert. | Erneut versuchen; dem Administrator melden, wenn es anhält. |
| 503 | Ein Speicher des Servers hat nicht geantwortet, der Bereich des Schlüssels ist auf dieser Instanz gerade nicht verfügbar, oder das Administrationsprotokoll hat den Eintrag nicht aufgenommen: Beim Wiederherstellen wurde nichts wiederhergestellt, beim Vergessen nichts vergessen. Analysieren, Maskieren und Wiederherstellen antworten auch mit 503, wenn die Einstellungen des Schlüssels noch angewendet wurden, als der Aufruf kam oder beantwortet wurde (the settings of this space changed while the call was answered: send it again): Vom Aufruf kam nichts zurück. |
Warten (Retry-After, wenn angegeben), dann erneut versuchen. |
| 507 | Nur beim Maskieren: Der Tresor des Schlüssels enthält bereits so viele Werte, wie er darf. Vom Aufruf kam nichts zurück, und nichts ging im Klartext hinaus. | Ein Administrator hebt die Grenze mit latet server keys limit an. |
Ein Maskieren oder ein Wiederherstellen lässt sich gefahrlos wiederholen: Ein Wert, den der Tresor
behalten hat, erhält wieder denselben Ersatzwert, und ein Wert, den ein gescheiterter Aufruf nicht
behalten hat, erhält wieder einen. Auch ein Vergessen lässt sich gefahrlos wiederholen: Ein Wert, der
schon fort ist, wird als unknown gezählt. Ein gescheiterter mask-Aufruf kann einige seiner neuen
Werte behalten haben (der Tresor eines Schlüssels
beschreibt, wann).
- Jede Antwort enthält
Cache-Control: no-store: Kein Cache behält einen Text oder einen Wert. - Jede Antwort enthält
Content-Security-Policy: default-src 'none'; sandbox: Ein Browser, der eine öffnet, führt darin kein Skript aus und behandelt sie nie als Seite des Servers. HTTP-Clients ignorieren diesen Header. Retry-After, in Sekunden, kommt mit jedem 429 und mit manchen 503.
Grenzen
Abschnitt betitelt „Grenzen“| Grenze | Wert | Festgelegt durch |
|---|---|---|
| Texte pro Aufruf, oder Werte pro Vergessen | 1.000 | Latet |
| Body eines Aufrufs | 8 MiB | apps_request_mb des Servers |
| Gleichzeitige Anfragen eines Schlüssels an die API für Anwendungen auf einer Instanz | 16 | requests_in_flight des Servers |
| Werte oder Ersatzwerte des Tresors, die die Texte eines Aufrufs nennen dürfen | 100.000 | Latet |
| Werte, die der Tresor eines Schlüssels fasst | 200.000 | vault_limit des Servers, oder die eigene Grenze des Schlüssels: latet server keys limit |
| Werte aus dem Tresor eines Schlüssels, die eine Instanz im Speicher hält | 5.000 | key_working_values des Servers |
Was der Server festhält
Abschnitt betitelt „Was der Server festhält“- Das Administrationsprotokoll erhält für jeden Wiederherstellungsaufruf, der beantwortet wird,
einen Eintrag
apps.unmasked, bevor die Antwort gesendet wird: die ID des Tokens, wie viele Texte und wie viele Werte wiederhergestellt wurden ({"token": "t_...", "texts": 3, "restored": 5}), und die Adresse des Clients. Nie ein Text oder ein Wert. Analysieren und Maskieren stehen nicht darin. Lesen Sie die Einträge mitlatet server log --action apps.unmasked. Jeder Aufruf zum Vergessen ist ein Eintragapps.forgotten, geschrieben in derselben Transaktion wie das Vergessen: die ID des Tokens, wie viele Werte angefragt, vergessen und nicht gefunden wurden ({"token": "t_...", "values": 2, "forgotten": 1, "unknown": 1}), und die Adresse des Clients. - Die Metriken zählen die Anfragen der API als
latet_http_requests_total{kind="apps"}, nach Status, und ihre Texte und Werte nach Operation:latet_apps_texts_total{operation}undlatet_apps_values_total{operation}(die Werte, die das Analysieren gefunden, das Maskieren ersetzt und das Wiederherstellen wiederhergestellt hat; beim Vergessen die angefragten und die vergessenen Werte). Sie haben kein Label für den Schlüssel: Wer was getan hat, steht im Administrationsprotokoll. - Das Log des Servers hat eine Zeile pro Aufruf: die Methode, den Pfad, den Status und die Dauer, nie einen Header, den Body oder einen Wert. Ablehnungen (401, 403, 404, 405, 413, 429 und die des Servers selbst) werden einmal pro Minute mit ihrer Anzahl zusammengefasst, statt je eine Zeile zu erhalten.
© 2026 Emanuele Casabona · USt-IdNr. IT02293040990 · Datenschutzerklärung · Impressum · latet.ai