URL de base — un seul hôte, pas sept

Audact expose une seule URL de base publique : https://api.audact.ai/v1. Il n’est pas nécessaire de configurer un nom d’hôte ou un port différent pour chaque service.

Fonctionnement

• Douze services indépendants (policy-engine, validator, evidence-layer, llm-proxy, tenant-management, audio-validator, aggregator, voice-gateway, agent-worker, webhook-worker, kb-worker, org-management) écoutent chacun sur leur propre port interne, mais aucun de ces ports n’est exposé publiquement.
• Un seul reverse proxy se place devant l’ensemble et achemine par chemin chaque requête vers le bon service en fonction du préfixe de l’URL — par exemple /v1/validate* → validator, /v1/calls* → evidence-layer, /v1/agents*//v1/voices*//v1/tools* → agent-worker, /v1/org/* → org-management, et ainsi de suite.
• Le routage applique le préfixe le plus long d’abord : les préfixes les plus précis sont testés avant leurs parents plus généraux (par exemple, /v1/validate-audio* est testé avant /v1/validate*).
• La référence de l’API en témoigne : chaque opération, quel que soit le service sous-jacent, est servie depuis https://api.audact.ai/v1.

Ce que cela signifie pour les intégrateurs

• Une seule valeur de configuration d’URL de base suffit à un client — il n’y a pas de table hôte/port par service à maintenir dans un SDK ou une intégration.
• Le préfixe du chemin suffit à déterminer quel service traite une requête ; les clients n’ont jamais besoin de savoir, ni de se soucier de savoir, lequel des services d’arrière-plan sert réellement un point de terminaison donné.
• La seule exception est la signalisation navigateur/WebRTC (/rtc/*), un chemin propre à LiveKit utilisé uniquement par le widget d’appel de test dans le navigateur, et non une surface d’API générale.

Configurer les SDK

Pointez le SDK vers l’hôte unique ; il ajoute lui-même /v1/.... Un / ou un /v1 final dans la valeur est supprimé.

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

Les remplacements par service (serviceUrls en TypeScript, <service>_url= en Python) ne sont nécessaires que pour les environnements locaux où chaque service écoute sur son propre port, et ils ont priorité sur l’URL de base.

Enveloppe d’erreur

Toutes les réponses d’erreur, quel que soit le service, utilisent la même structure de corps :

{
  "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 et message sont toujours présents. hint, details et request_id peuvent être absents (ils sont omis lorsqu’ils sont vides). Indiquez request_id lorsque vous contactez le support. Les réponses limitées par le débit (429) portent aussi un en-tête Retry-After. Les SDK exposent ces champs sur leurs types d’erreur (par exemple err.code et err.requestId en TypeScript).