Getting Started

Diese Seite führt einmal durch den vollen Cortina-Round-Trip: Session erstellen, Text anonymisieren, einen LLM-Call simulieren, das Ergebnis deanonymisieren. Erst per cURL gegen die Live-API, dann mit den SDKs.

Prerequisites

1. Einen API-Key.

   Erstelle einen Account auf platform.lissa-ai.de/register. Danach im Dashboard API Keys öffnen, Create API Key wählen und den Key einmalig kopieren. Rotation und Widerruf laufen ebenfalls über platform.lissa-ai.de.

2. Ein Terminal mit curl (für den ersten Teil) oder Node ≥ 18 / Python ≥ 3.10 (für den SDK-Teil).

3. Den Key in einer Umgebungsvariable. Alle folgenden Beispiele nehmen CORTINA_API_KEY aus dem Environment.

   Bash / zsh / Git Bash

   export CORTINA_API_KEY="lissa_live_<dein-key>"

   PowerShell

   $env:CORTINA_API_KEY = "lissa_live_<dein-key>"

   export funktioniert nicht in PowerShell. Dort immer $env:CORTINA_API_KEY = ... verwenden.

Base URL

Umgebung	Base URL	Wann verwenden
Production	https://api.lissa-ai.de/v1/cortina	Für alle produktiven Clients und Beispiele in dieser Doku.
Lokaler Service	http://localhost:8000/v1	Direkter FastAPI-Service ohne Gateway-Prefix.
Lokaler Public-Prefix-Check	http://localhost:8000/v1/cortina	Kompatibilitätscheck gegen denselben Prefix wie Production.

Der Service akzeptiert lokal sowohl /v1/... als auch /v1/cortina/.... Production-Clients sollen immer den öffentlichen Prefix https://api.lissa-ai.de/v1/cortina/... verwenden.

First Request — cURL

Die vier Calls unten reichen für einen vollen Round-Trip. Die session_id aus Schritt 1 muss im Body der Folge-Calls stehen (nicht in einem Header — das ist die häufigste Verwechslung beim ersten Anlauf).

1. Session erstellen.

   curl -sS -X POST https://api.lissa-ai.de/v1/cortina/session \
     -H "Authorization: Bearer $CORTINA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ttl_seconds": 600}'

   Antwort:

   {
     "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f",
     "expires_at": "2026-05-06T20:00:00Z",
     "status": "active"
   }

   Die session_id für die nächsten Schritte merken. ttl_seconds ist optional, defaultet auf 3600 und muss zwischen 60 und 86400 liegen.

2. Text anonymisieren.

   curl -sS -X POST https://api.lissa-ai.de/v1/cortina/anonymize \
     -H "Authorization: Bearer $CORTINA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Bitte auf IBAN DE89 3704 0044 0532 0130 00 überweisen. Tel: +49 6131 1234567",
       "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f"
     }'

   Antwort (gekürzt):

   {
     "anonymized_text": "Bitte auf IBAN [DE_IBAN_1] überweisen. Tel: [DE_PHONE_NUMBER_1]",
     "entities": [
       { "entity_type": "DE_IBAN", "start": 16, "end": 41, "placeholder": "[DE_IBAN_1]", "confidence": 1.0 },
       { "entity_type": "DE_PHONE_NUMBER", "start": 58, "end": 75, "placeholder": "[DE_PHONE_NUMBER_1]", "confidence": 0.95 }
     ],
     "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f",
     "audit_flags": []
   }

   Den anonymized_text kannst du jetzt sicher an dein LLM weitergeben. Die Original-PII liegt verschlüsselt in der Session.

3. Antwort deanonymisieren.

   Angenommen das LLM antwortet mit "Ich bestätige die Überweisung an [DE_IBAN_1]." — diesen Text ans Deanonymize-Endpoint:

   curl -sS -X POST https://api.lissa-ai.de/v1/cortina/deanonymize \
     -H "Authorization: Bearer $CORTINA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Ich bestätige die Überweisung an [DE_IBAN_1].",
       "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f"
     }'

   Antwort:

   {
     "original_text": "Ich bestätige die Überweisung an DE89 3704 0044 0532 0130 00.",
     "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f"
   }

4. Session löschen.

   Wenn der Workflow fertig ist, kann die Session sofort gelöscht werden. Das Redis-Mapping wird dabei entfernt.

   curl -sS -X DELETE https://api.lissa-ai.de/v1/cortina/session/018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f \
     -H "Authorization: Bearer $CORTINA_API_KEY"

   Erfolg gibt 204 No Content zurück.

Pfad-Konvention

Alle Cortina-Endpoints leben unter https://api.lissa-ai.de/v1/cortina/... — nicht unter /v1/.... Auch wenn das interne OpenAPI-Schema die Pfade ohne den cortina/-Prefix listet (das ist die Server-relative Sicht), gehört der Prefix in jeden Production-Client-Call.

Häufige Fehler

Symptom	Ursache	Lösung
export: The term 'export' is not recognized	export wurde in PowerShell verwendet.	$env:CORTINA_API_KEY = "..." verwenden.
{"detail":"Not Found"} oder {"error":{"code":"http_404",...}}	Falsche Base URL oder altes Deployment ohne Public-Prefix-Alias.	In Production https://api.lissa-ai.de/v1/cortina/... verwenden.
401 unauthorized	API-Key fehlt, ist falsch geschrieben oder widerrufen.	Authorization: Bearer ... prüfen.
422 validation_error	Body ungültig, session_id fehlt, Text ist leer oder TTL liegt außerhalb 60..86400.	Request-Body mit den Beispielen oben abgleichen.
404 session_not_found	Session ist abgelaufen, gelöscht oder gehört zu einem anderen Tenant.	Neue Session erstellen und diese ID verwenden.
429 rate_limit_exceeded	Per-Key-Limit erreicht.	Retry-After und X-RateLimit-* beachten.

Same flow with the SDKs

TypeScript

import { CortinaClient } from "@lissa-ai/cortina";

const cortina = new CortinaClient({ apiKey: process.env.CORTINA_API_KEY! });

// 1. Anonymisieren — Convenience-Pfad mit Auto-Session
const masked = await cortina.anonymize(
  "Bitte auf IBAN DE89 3704 0044 0532 0130 00 überweisen. Tel: +49 6131 1234567",
);
console.log(masked.anonymizedText);
// "Bitte auf IBAN [DE_IBAN_1] überweisen. Tel: [DE_PHONE_NUMBER_1]"

// 2. Den anonymisierten Text an dein LLM
const llmReply = await callMyLLM(masked.anonymizedText);

// 3. Originale wieder einsetzen
const restored = await cortina.deanonymize({
  text: llmReply,
  sessionId: masked.sessionId,
});
console.log(restored.originalText);

Python

import asyncio
import os
from cortina import AsyncCortinaClient

async def main() -> None:
    async with AsyncCortinaClient(api_key=os.environ["CORTINA_API_KEY"]) as cortina:
        # 1. Anonymisieren
        masked = await cortina.anonymize(
            "Bitte auf IBAN DE89 3704 0044 0532 0130 00 überweisen. "
            "Tel: +49 6131 1234567"
        )
        print(masked.anonymized_text)
        # "Bitte auf IBAN [DE_IBAN_1] überweisen. Tel: [DE_PHONE_NUMBER_1]"

        # 2. Den anonymisierten Text an dein LLM
        llm_reply = await call_my_llm(masked.anonymized_text)

        # 3. Originale wieder einsetzen
        restored = await cortina.deanonymize(
            text=llm_reply, session_id=masked.session_id
        )
        print(restored.original_text)

asyncio.run(main())

Was hinter den Kulissen passiert

Wenn du anonymize aufrufst, läuft Text durch eine vierstufige Pipeline (Pattern-Recognizer → spaCy NER → Context-LLM → Adversarial-Loop), und das Original-Mapping wird verschlüsselt in Redis abgelegt.

→ 4-Stage Pipeline im Detail → Sessions & Mapping-Lifecycle