API Conventions#
Rules that apply to every endpoint.
Base URL and transport#
All requests use HTTPS. Responses are JSON (application/json; charset=utf-8); audio responses are audio/mpeg. GET requests use query parameters, write requests a JSON body.
Tenant context#
| Mechanism | Behavior |
|---|---|
X-Tenant header | Sets the tenant explicitly (overrides everything) |
| Host detection | serielle-… hosts map to tenant ssr, everything else to bbe |
Isolation is enforced server-side: there is no way to read or write another tenant's data.
Versioning#
The /v2/ namespace versions the API. The contract version (contract) is visible in /health and follows semantic versioning.
Error format#
Errors come back as JSON with a descriptive error code and, where helpful, a message:
{ "error": "phone_required" }| HTTP status | Meaning |
|---|---|
| 400 | Request incomplete or invalid |
| 404 | Resource or route does not exist |
| 429 | Rate limit reached (public lead intake) |
| 502 | Downstream engine (TTS/STT) unreachable |
CORS#
The console UIs are allow-listed. The only open surface is the public lead intake /v2/public/leads — protected by a honeypot field and a rate limit (10 requests per IP per minute), and it can only write, never read.
Languages#
Speech processing (TTS and STT) is verified for German; the underlying models are multilingual.