Basis-URL — één host, niet zeven

Audact biedt één publieke basis-URL: https://api.audact.ai/v1. Het is niet nodig om per dienst een andere hostnaam of poort te configureren.

Hoe het werkt

• Twaalf onafhankelijke diensten (policy-engine, validator, evidence-layer, llm-proxy, tenant-management, audio-validator, aggregator, voice-gateway, agent-worker, webhook-worker, kb-worker, org-management) luisteren elk op hun eigen interne poort, maar geen van die poorten is publiek toegankelijk.
• Een enkele reverse proxy staat voor alle diensten en routeert elk verzoek via het pad naar de juiste backenddienst op basis van het URL-voorvoegsel — bijv. /v1/validate* → validator, /v1/calls* → evidence-layer, /v1/agents*//v1/voices*//v1/tools* → agent-worker, /v1/org/* → org-management, enzovoort.
• Routering werkt op basis van langste voorvoegsel eerst: specifiekere voorvoegsels worden vergeleken vóór hun bredere bovenliggende elementen (bijv. wordt /v1/validate-audio* gecontroleerd vóór /v1/validate*).
• De API-referentie weerspiegelt dit: elke bewerking, over alle onderliggende diensten heen, wordt geserveerd vanaf https://api.audact.ai/v1.

Wat dit betekent voor integratoren

• Één basis-URL-configuratiewaarde is alles wat een client nodig heeft — er is geen host-/poortkaart per dienst bij te houden in een SDK of integratie.
• Het padvoorvoegsel alleen bepaalt welke dienst een verzoek afhandelt; clients hoeven nooit te weten of te bekommeren welke van de backenddiensten een bepaald eindpunt daadwerkelijk bedient.
• De enige uitzondering is browser-/WebRTC-signalering (/rtc/*): een LiveKit-specifiek pad dat alleen wordt gebruikt door de in-browser testoproepwidget en geen algemeen API-oppervlak is.

De SDK's configureren

Wijs de SDK naar de enkele host; de SDK voegt zelf /v1/... toe. Een afsluitende / of /v1 in de waarde wordt verwijderd.

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")

Dienstspecifieke overschrijvingen (serviceUrls in TypeScript, <service>_url= in Python) zijn alleen nodig voor lokale stacks waarbij elke dienst op zijn eigen poort luistert, en ze hebben voorrang op de basis-URL.

Fout-envelope

Elke foutrespons van elke dienst gebruikt dezelfde bodystructuur:

{
  "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 en message zijn altijd aanwezig. hint, details en request_id kunnen ontbreken (ze worden weggelaten als ze leeg zijn). Vermeld request_id bij contact met de ondersteuning. Antwoorden met rate-limiting (429) bevatten ook een Retry-After-header. De SDK's stellen deze velden beschikbaar in hun fouttypen (bijv. err.code en err.requestId in TypeScript).