Basis-URL — Ein Host, nicht sieben

Audact stellt eine einzige öffentliche Basis-URL bereit: https://api.audact.ai/v1. Es ist nicht erforderlich, für jeden Dienst einen anderen Hostnamen oder Port zu konfigurieren.

So funktioniert es

• Zwölf unabhängige Dienste (policy-engine, validator, evidence-layer, llm-proxy, tenant-management, audio-validator, aggregator, voice-gateway, agent-worker, webhook-worker, kb-worker, org-management) lauschen jeweils auf ihrem eigenen internen Port; keiner dieser Ports ist öffentlich zugänglich.
• Ein einzelner Reverse-Proxy sitzt vor allen Diensten und leitet jede Anfrage per Pfad-Routing an den richtigen Backend-Dienst weiter, basierend auf dem URL-Präfix — z. B. /v1/validate* → validator, /v1/calls* → evidence-layer, /v1/agents*//v1/voices*//v1/tools* → agent-worker, /v1/org/* → org-management und so weiter.
• Das Routing erfolgt nach dem Longest-Prefix-First-Prinzip: Spezifischere Präfixe werden vor ihren allgemeineren übergeordneten Präfixen abgeglichen (z. B. wird /v1/validate-audio* vor /v1/validate* geprüft).
• Die API-Referenz spiegelt dies wider: Jeder Vorgang wird über alle zugrunde liegenden Dienste hinweg unter https://api.audact.ai/v1 bereitgestellt.

Was dies für Integratoren bedeutet

• Ein einziger Basis-URL-Konfigurationswert ist alles, was ein Client benötigt — es muss keine Host-/Port-Zuordnung pro Dienst in einem SDK oder einer Integration gepflegt werden.
• Das Pfadpräfix allein bestimmt, welcher Dienst eine Anfrage bearbeitet; Clients müssen nie wissen oder beachten, welcher der Backend-Dienste einen bestimmten Endpunkt tatsächlich bedient.
• Die einzige Ausnahme ist Browser-/WebRTC-Signalisierung (/rtc/*): ein LiveKit-spezifischer Pfad, der nur vom Browser-Test-Widget verwendet wird und keine allgemeine API-Oberfläche darstellt.

SDKs konfigurieren

Verweisen Sie das SDK auf den einzigen Host; es fügt /v1/... selbst an. Ein abschließendes / oder /v1 im Wert wird entfernt.

import { AudactClient } from "@audactcore/sdk";

const client = new AudactClient({
  apiKey: process.env.AUDACT_API_KEY!,
  baseUrl: "https://api.audact.ai",
});

from audact import AudactClient

client = AudactClient(api_key="...", base_url="https://api.audact.ai")

Dienstspezifische Überschreibungen (serviceUrls in TypeScript, <service>_url= in Python) werden nur für lokale Stacks benötigt, bei denen jeder Dienst auf seinem eigenen Port lauscht; sie haben Vorrang vor der Basis-URL.

Fehler-Envelope

Jede Fehlerantwort von jedem Dienst verwendet dieselbe Body-Struktur:

{
  "error": {
    "code": "INVALID_COUNTRY",
    "message": "Country code 'XX' is not supported",
    "hint": "Use an ISO 3166-1 alpha-2 code such as NL or DE",
    "details": {"supported_countries": ["NL", "DE"]},
    "request_id": "req_abc123"
  }
}

code und message sind immer vorhanden. hint, details und request_id können fehlen (sie werden weggelassen, wenn sie leer sind). Geben Sie request_id an, wenn Sie den Support kontaktieren. Anfragen mit Rate-Limiting (429) enthalten außerdem einen Retry-After-Header. Die SDKs stellen diese Felder in ihren Fehlertypen zur Verfügung (z. B. err.code und err.requestId in TypeScript).