API-Dokumentation

Die Regunow-API verwendet HTTPS, Bearer-Authentifizierung und das versionierte Präfix /api/v1. Diese Dokumentation ist ohne Konto zugänglich. API-Anfragen erfordern aktiven Pro-Zugang und die Zustimmung zu den aktuellen Richtlinien.

1. Melden Sie sich bei Regunow an und erstellen Sie unter Einstellungen → API-Schlüssel einen Schlüssel.
2. Bewahren Sie den geheimen Schlüssel sicher auf. Er wird nur bei der Erstellung einmal angezeigt.
3. Legen Sie Host und Schlüssel fest und senden Sie Ihre erste Frage über ein Backend oder eine vertrauenswürdige Automatisierung.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

Die Antwort steht in output.content. Quellenangaben und berechnete Credits sind in der Antwort enthalten. Diese Anfrage verbraucht Credits. Verwenden Sie für jede neue Frage einen neuen Idempotenzschlüssel.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

Senden Sie Ihren API-Schlüssel bei jeder Anfrage im HTTP-Header Authorization. Schlüssel in URLs, Cookies oder Anfrageinhalten werden nicht akzeptiert.

Authorization: Bearer rgn_live_...

Speichern Sie Schlüssel in einer Umgebungsvariable oder einem Secret-Manager. Halten Sie sie aus Browsercode, mobilen App-Paketen, öffentlichen Repositorys und Protokollen fern. Browserzugriff über verschiedene Ursprünge ist nicht aktiviert; senden Sie Anfragen über Ihren Server.

Deaktivierte, gelöschte oder abgelaufene Schlüssel werden sofort nicht mehr zur Authentifizierung akzeptiert. Regunow speichert nur einen Hash des Geheimnisses und kann vorhandene geheime Schlüssel nicht erneut anzeigen. Erstellen Sie bei Bedarf einen Ersatzschlüssel.

Pro-Zugang und Richtlinienzustimmung werden bei jeder Anfrage geprüft. Bei legal_acceptance_required muss sich der Schlüsselinhaber anmelden und Zustimmung zu den rechtlichen Bedingungen öffnen. API-Schlüssel können keine Richtlinien akzeptieren.

GET/api/v1/models

Ermitteln Sie unterstützte Modelle, Aufwandsstufen, Rechtsräume, Antwortsprachen und Funktionen. Dieser authentifizierte Endpunkt verursacht keine gesonderten Credit-Kosten und eignet sich zur Schlüsselprüfung vor einer Chat-Anfrage.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Verwenden Sie die Katalogwerte Ihrer Bereitstellung. Lassen Sie im Rechtsraummodus model und effort weg, um die zulässigen Standardwerte zu nutzen. Falls angegeben, müssen sie der Standardauswahl Sonnet 4.6 / Hoch entsprechen. Bei Antworten ohne Anhänge verwaltet der Abrufdienst das Antwortmodell; das Modellfeld der Antwort beschreibt die validierte Auswahl.

POST/api/v1/chat/completions

Senden Sie einen JSON-Inhalt mit einem messages-Array. Standardmäßig liefert die API die vollständige Antwort als JSON. Setzen Sie stream auf true, um Text schrittweise zu erhalten.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

Ersetzen Sie YOUR_FILE_ID durch die UUID eines erfolgreichen Uploads. Senden Sie bei Folgefragen den relevanten Benutzer- und Assistentenverlauf sowie erneut die gewünschten file_ids. Die API speichert Gesprächsverlauf und Anhänge nicht automatisch für Folgeanfragen.

Systemnachrichten und unbekannte Felder werden abgelehnt. Bild- und Berichtserstellung, Audioeingaben und Zugriff auf gespeicherte Erinnerungen sind über diese API nicht verfügbar. Hochgeladene Bilder können als Eingabe für Fragen verwendet werden.

Eine erfolgreiche Chat-Anfrage liefert object: "regunow.chat.completion", die Antwort, Quellenmetadaten, Nutzung und Zeitmessungen. Die folgenden Werte dienen der Veranschaulichung.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content enthält den maßgeblichen Antworttext. Zitatpositionen beziehen sich auf diese endgültige Zeichenfolge; sourceIndexes verweist auf Einträge in output.sources.
• Quellen enthalten Titel, Dateiname, MIME-Typ, URI und abgerufenen Auszug. Zeigen Sie Auszüge und Zitate zusammen mit der Antwort an.
• Eine Quellen-URI dient als Speicherortangabe und kann auf privaten Speicher verweisen. Verwenden Sie nur öffentliche Herausgeber-URLs als zugängliche Links. Die API bietet weder Downloads regulatorischer Quelldateien noch deren Übersetzung.
• Bei Anhängen identifiziert output.input_files die übergebenen Dateien. Anhangsquellen haben eine file_id; regulatorische und Webquellen haben file_id: null. Anhangs-URIs sind null.
• Das Vorhandensein einer Eingabedatei beweist nicht, dass sie jede Aussage stützt. Modelle können Inline-Zitate auslassen; Bilder oder Scans können leere Auszüge haben.

Tokenzahlen können null sein, wenn der Abrufdienst sie nicht ausgibt; das bedeutet unbekannt, nicht null Tokens. charged_credits ist die erfasste Kundenbelastung. created ist ein Unix-Zeitstempel in Sekunden; Latenzwerte sind Millisekunden.

Jede Endpunktantwort enthält einen X-Request-Id-Header. Bewahren Sie diese Kennung zur Fehlerdiagnose auf. Chat- und Fehler-JSON enthalten außerdem request_id.

Setzen Sie "stream": true. Die Antwort verwendet text/event-stream. Ergänzen Sie bei cURL -N, um die Ausgabepufferung zu deaktivieren.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

Lesen Sie vollständige SSE-Ereignisse, getrennt durch Leerzeilen. Ein Netzwerkblock kann Teile eines Ereignisses oder mehrere Ereignisse enthalten. Hängen Sie eingehendes choices[0].delta.content an. Ignorieren Sie Kommentar-Heartbeats, die mit : beginnen.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

Das letzte Metadatenereignis hat ein leeres choices-Array. Lesen Sie endgültige Antwort, Zitate und Quellen aus regunow.output, Zeiten aus regunow.latency und Credits aus regunow.usage. Tokenzahlen stehen in usage.prompt_tokens und usage.completion_tokens.

Abruf und Zitatverarbeitung können Pausen verursachen. Betrachten Sie Text bis zu den abschließenden Metadaten als vorläufig. Fehler nach Streamingbeginn erscheinen als error-Objekt, gefolgt von [DONE]; HTTP 200 allein bestätigt keinen Erfolg. Frühere Authentifizierungs- oder Validierungsfehler liefern normale JSON-Fehlerantworten.

Die Wiederholung eines abgeschlossenen Vorgangs bleibt SSE und liefert die gespeicherte Antwort als einzelnen Textblock mit X-Idempotent-Replayed: true.

Laden Sie Dokumente oder Bilder hoch und fügen Sie ihre IDs einer Chat-Anfrage hinzu. Dateien teilen Bibliothek und Speicherquote des Schlüsselinhabers. Dokumente dürfen bis zu 10 MiB, Bilder bis zu 5 MiB groß sein.

Direkter Upload (empfohlen)

Dieser Ablauf in drei Schritten sendet die Originaldateibytes direkt an den Speicher und umgeht Größenlimits des Anwendungs-Anfrageinhalts. Nutzen Sie ihn für gehostete Integrationen, insbesondere für größere Dateien.

POST/api/v1/files/upload-intents

Senden Sie nur name, mime_type und bytes (die genaue Dateigröße). Bei Erfolg erhalten Sie HTTP 201 mit der ID einer ausstehenden Datei und einer 300 Sekunden gültigen signierten Upload-URL.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

Setzen Sie FILE_ID auf die zurückgegebene id. Nutzen Sie upload_method, upload_url und upload_headers aus der Antwort, um die unveränderten Originalbytes hochzuladen. Geben Sie die genaue Content-Length an. Senden Sie den Regunow-API-Schlüssel nicht an die Upload-URL und protokollieren Sie keine signierten URLs.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

Senden Sie {} mit einem anderen Idempotenzschlüssel. Der Abschluss validiert die Bytes und liefert HTTP 200 mit einer verfügbaren Datei. Ihre ID kann erst nach erfolgreichem Abschluss in file_ids verwendet werden.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

Läuft die Upload-URL ab, löschen Sie die ungenutzte ausstehende Datei und bereiten Sie mit einem neuen Schlüssel einen weiteren Upload vor. Eine Wiederholung verlängert die URL-Gültigkeit nicht. Prüfen Sie nach einem unklaren Abschluss zunächst den Dateistatus. Ist er weiterhin ausstehend, wiederholen Sie den Abschluss mit einem neuen Idempotenzschlüssel; der alte liefert sein gespeichertes Ergebnis. Der Abschluss einer bereits verfügbaren Datei liefert ihre Metadaten.

Multipart-Upload

POST/api/v1/files

Senden Sie kleinere Dateien über ein einzelnes multipart/form-data-Feld namens file. Senden Sie Originalbytes, kein Base64 und keine Remote-URL. Ihr Hosting-Gateway kann ein kleineres Inhaltslimit als die API-Dateigrenze vorgeben.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

Ein erfolgreicher Upload liefert HTTP 201 mit einer verfügbaren Datei; ein gesonderter Abschlussaufruf ist nicht nötig.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

Dateien auflisten, abrufen und löschen

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Schlüssel desselben Kontos können auf dessen verfügbare Bibliotheksdateien zugreifen. Fehlende Dateien und Dateien anderer Konten liefern beide 404. Bedient Ihre Anwendung mehrere Benutzer über ein Konto, prüfen Sie deren Berechtigungen selbst, bevor Sie Dateien anhängen oder löschen.

Ausstehende und fehlgeschlagene Uploads belegen Quote, bis die Bereinigung erfolgreich ist. Unvollständige Uploads über 24 Stunden sind zur Bereinigung berechtigt. Verfügbare Dateien haben die Upload-Validierung bestanden; die Extraktion erfolgt bei einer Frage. Beschädigte, verschlüsselte oder unlesbare Dokumente können daher während der Analyse noch fehlschlagen.

Chat-Anfragen, Uploads und Löschungen erfassen gemessene Nutzung. Modellkatalog und Dateimetadatenabfragen haben keine gesonderten Credit-Kosten. Dokumentextraktion und Bildanalyse werden über die Chat-Anfrage berechnet.

Lesen Sie die Vorgangsbelastung aus usage.charged_credits. Ein Credit entspricht 1.000.000 Mikrocredits. Schlüssel-Credit-Limits sind vom Kontoguthaben getrennt; beide können Anfragen verhindern. Prüfen Sie Nutzung und konfigurieren Sie Credit-Limits unter Einstellungen → API-Schlüssel.

Modellkontext- und Bildlimits gelten weiterhin, auch wenn jede Nachricht und jeder Anhang innerhalb der API-Limits liegt. Schlüsselbudgets werden in rollierenden täglichen, wöchentlichen oder monatlichen Zeiträumen zurückgesetzt, beginnend mit der Schlüsselerstellung oder dem Wechsel des vorherigen Zeitraums.

Eine Anfrage, die mit verfügbarem Budget beginnt, kann ein kleines Restguthaben geringfügig überschreiten, da die endgültigen Kosten erst nach der Generierung feststehen. Sobald das Limit erreicht ist, stoppen neue Chat-Anfragen und Dateiänderungen. Reservierungen verhindern, dass parallele Anfragen dasselbe verfügbare Schlüsselbudget ausgeben.

Senden Sie für jede Chat-Anfrage, jeden Upload, Upload-Abschluss und jede Löschung einen Idempotency-Key. Er ist optional, aber dringend empfohlen, um nach Verbindungsfehlern doppelte Arbeit und Kosten zu vermeiden.

Idempotency-Key: a-unique-key-for-this-operation

• Erzeugen Sie für jeden neuen Vorgang einen eindeutigen Schlüssel und speichern Sie ihn zusammen mit der ursprünglichen Anfrage.
• Wiederholen Sie den Vorgang mit demselben API-Schlüssel, Idempotenzschlüssel und unveränderten Eingaben. Nach der Abrechnung können gespeicherter Status und Antwort 24 Stunden lang ohne erneuten Anbieteraufruf oder weitere Kosten wiedergegeben werden.
• Eine Wiederholung enthält X-Idempotent-Replayed: true. Die Wiederverwendung mit anderen Eingaben oder während die erste Anfrage noch läuft liefert 409.
• Gespeicherte Ergebnisse können Fehler enthalten. Derselbe Schlüssel kann denselben Fehler zurückgeben, statt erneut auszuführen. Prüfen Sie das Ergebnis vor einem neuen Vorgang.
• Nach Ablauf des Wiederholungsfensters startet die Wiederverwendung eines Schlüssels eine neue Anfrage und kann weitere Kosten verursachen.

Verwenden Sie bei vorübergehenden Netzwerk-, Ratenlimit- oder Dienstfehlern exponentiell zunehmende Wartezeiten. Behalten Sie den Idempotenzschlüssel bei, solange das Anfrageergebnis unklar ist. Wiederholen Sie ungültige Eingaben, abgelaufene Anmeldedaten oder ausgeschöpfte Credits erst nach Behebung der Ursache.

Das Löschen einer Datei entfernt während des Wiederholungsfensters keine bereits gespeicherte Chat- oder Upload-Antwort. Eine Upload-Wiederholung nach der Löschung liefert die ursprüngliche Antwort und erstellt die Datei nicht erneut.

Fehler verwenden eine stabile JSON-Struktur. Prüfen Sie error.code zur Behandlung und bewahren Sie request_id oder den Header X-Request-Id für Supportanfragen auf.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}