LLM Router API Documentatie
Een centrale pagina voor alle LLM Router API's: consumer endpoints, async jobs, adminbeheer, provider-routing, usage analytics, secrets en de ingebedde Swagger UI.
/v1
Interne API /api/v1
Admin API /admin/api
Secrets API /api/secrets
Wat doet de LLM Router?
De LLM Router is de centrale RD Workx gateway voor LLM-verkeer. Applicaties hoeven niet rechtstreeks tegen OpenAI, OpenRouter, Codex CLI, Claude CLI of Hermes-profielen te praten. Zij gebruiken een eigen router API key en sturen requests naar de router. De router kiest daarna op basis van classificatie, API-key voorkeuren, providerconfiguratie en fallbackregels welke upstream provider en welk model worden gebruikt.
De router registreert daarnaast tokenverbruik, latency, fouten, input/output logs, async jobstatus, queue-statistieken en provider health checks. Daardoor ontstaat een centraal beheerpunt voor kosten, limieten, routing en auditbaarheid.
Consumer API
Voor applicaties die tekstgeneratie nodig hebben. Compatibel met OpenAI clients via /v1/chat/completions en /v1/models.
Async job API
Voor langere taken waarbij de caller een job aanmaakt, status ophaalt en eventueel annuleert.
Admin API
Voor beheer van keys, usage, providers, route rules, live log, provider tests en testlab.
Secrets API
Voor encrypted opslag en gecontroleerde ontsluiting van API keys, client/secret pairs, database credentials en env groups.
Authenticatie en autorisatie
Consumer API key
Consumers sturen Authorization: Bearer hlr_.... De router hasht de aangeboden key en zoekt die op in api_keys.key_hash. Alleen actieve keys mogen calls doen. Per key kunnen tokenlimieten en een voorkeursprovider/model zijn ingesteld.
Admin token
Admin endpoints gebruiken X-Admin-Token of Authorization: Bearer .... Dit token is bedoeld voor beheerders en de admin UI. Het geeft toegang tot keybeheer, providerbeheer, usage, logs en secret-metadata.
Master key
Volledige secretwaarden worden alleen gedecrypt met de master key uit HERMES_LLM_ROUTER_MASTER_KEY. De Secrets API accepteert deze via X-Master-Key of bearer authorization. De key zelf staat niet in de database.
Secretwaarden horen niet in logs, documentatie, screenshots of commits. Deze pagina toont alleen placeholders en beschrijft de flow; echte waarden worden nooit hardcoded.
Consumer API
De consumer API is bedoeld voor applicaties die de router als LLM-provider gebruiken. De belangrijkste route is OpenAI-compatible, zodat bestaande SDK's met een andere base URL kunnen werken.
| Endpoint | Doel | Authenticatie | Belangrijk gedrag |
|---|---|---|---|
GET/health | Readiness/health check. | Geen. | Geeft huidige provider/model samenvatting terug. |
GET/v1/models | OpenAI-compatible modellijst. | Consumer API key. | Retourneert hermes-current plus alle modellen die enabled providers adverteren. |
POST/v1/chat/completions | Synchrone of streaming chat completion. | Consumer API key. | Ondersteunt classification, metadata, stream, async, tools en OpenAI-compatible velden. Een expliciet model uit /v1/models wordt exact gerouteerd; een onbekend of ongeschikt model geeft HTTP 422 model_not_available. |
POST/v1/embeddings | OpenAI-compatible embeddings via een beheerde provider. | Consumer API key. | METADATA_ONLY-keys verwerken embeddings en synchrone/streaming chat zonder inhoud of persistente routerjob op te slaan; asynchrone calls zijn uitgeschakeld. |
curl -H "Authorization: Bearer $LLM_ROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"hermes-current","classification":"medium","messages":[{"role":"user","content":"Schrijf een korte tekst."}]}' \
http://host:8787/v1/chat/completions
Classificaties zijn light, medium, frontier, document, image en voice. Met hermes-current gebruikt de router classificatie, keyvoorkeuren en fallbacks. Een ander model-ID beperkt de route tot een geschikte provider die exact dat model aanbiedt. Bij streaming controleert de router vooraf of de gekozen route streaming ondersteunt.
Async job API
De job API gebruikt het RD Workx response-envelope patroon met {"success":true,"data":...}. Jobs worden opgeslagen in llm_jobs; Redis is alleen een wakeup/queue-laag wanneer die is ingeschakeld. PostgreSQL blijft de source of truth.
| Endpoint | Doel | Response |
|---|---|---|
POST/api/v1/llm/jobs | Maakt altijd een async LLM job aan. | Jobrecord met status, classificatie, timestamps en requestmetadata. |
GET/api/v1/llm/jobs/{job_id} | Haalt status/resultaat van een job op. | Jobrecord met response of error zodra afgerond. |
POST/api/v1/llm/jobs/{job_id}/cancel | Vraagt annulering aan. | Bij queued jobs wordt status canceled; bij running jobs wordt cancel_requested gezet. |
Admin API
De admin API ondersteunt de beheerinterface. Deze endpoints zijn niet bedoeld voor gewone LLM-consumers. Gebruik ze voor operationeel beheer, dashboards, providerconfiguratie en gecontroleerde supportacties.
Keys en limieten
/admin/api/keys maakt, lijst, wijzigt, revoke't en verwijdert router API keys. Nieuwe keys worden eenmalig volledig teruggegeven; daarna toont de UI normaliter alleen prefix/metadata.
Usage en logs
/admin/api/usage geeft tokenverbruik, latency, statusverdeling, modelverdeling, headroom-statistieken en recente calls terug. Clear endpoints verwijderen usage/call logs wanneer een beheerder dat expliciet doet.
Providers en routing
/admin/api/router/providers beheert OpenAI-compatible providers, Hermes CLI-profielen, Codex CLI en Claude CLI. /admin/api/router/routes beheert primaire en fallbackroutes per classificatie.
Provider tests en live status
Provider tests controleren bereikbaarheid, modellijst, chat en streaming. Router status/live endpoints tonen queue, Redis, worker threads, provider health en recente jobs.
Secrets API en secret types
Secrets worden centraal beheerd in de tabel secrets_store. Elk record heeft type, name, description, gemaskeerde previews en een fernet:-encrypted payload. Volledige waarden worden alleen teruggegeven na master-key validatie.
| Type | Wat is het? | Opgeslagen payload | Typisch gebruik |
|---|---|---|---|
api_key | Een enkel bearer token of provider key. | name, description, api_key. | OpenAI/OpenRouter key koppelen aan een provider via api_key_secret_id. |
client_secret_pair | Een OAuth-achtig paar met publieke client identifier en private secret. | name, description, client_id, secret. | Integraties waarbij een token exchange of client-credentials flow nodig is. |
database | Databasecredentialset voor beheer of deploymentdoorvoer. | database_name, user, password, database_url. | Alleen voor gecontroleerde ontsluiting; applicaties horen via de API-laag te werken. |
env_group | Een named groep environment variables. | name, description, variables[] met name, value, value_type. | Een set runtimevariabelen ophalen voor een app, host of deploymentcontext. |
Endpoints
| Endpoint | Doel | Geeft volledige waarden? |
|---|---|---|
GET/admin/api/secrets | Adminlijst met metadata en previews voor UI. | Nee. |
POST/admin/api/secrets | Nieuw secret record aanmaken. | Nee, alleen metadata/previews. |
PATCH/admin/api/secrets/{secret_id} | Secret record vervangen/bijwerken. | Nee. |
DELETE/admin/api/secrets/{secret_id} | Secret verwijderen. | Nee. |
POST/admin/api/secrets/{secret_id}/values | Admin copy endpoint met master key in body. | Ja. |
GET/api/secrets?type=env_group | Consumer/system API voor lijst op optioneel type. | Ja, met master key. |
GET/api/secrets/{secret_id} | Ophalen op technische ID. | Ja, met master key. |
GET/api/secrets/by-name/{name}?type=api_key | Ophalen op herkenbare naam en optioneel type. | Ja, met master key. |
curl -H "X-Master-Key: $HERMES_LLM_ROUTER_MASTER_KEY" \ "http://host:8787/api/secrets/by-name/OpenRouter?type=api_key"
Verschil tussen API key, client/secret pair, database en env group
API key
Een API key is een enkel geheim waarmee een service zichzelf direct authenticeert. Binnen de router bestaan twee varianten: router consumer keys in api_keys en externe provider keys als encrypted api_key secret in secrets_store. Consumer keys worden gehasht voor authenticatie; provider keys worden encrypted bewaard zodat de router ze kan decrypten bij een upstream call.
Client/secret pair
Een client/secret pair bestaat uit een client identifier en een private secret. De client ID is vaak niet genoeg om toegang te krijgen; de secret bewijst de identiteit bij een token endpoint of integratie. In de router worden beide velden samen encrypted opgeslagen, en in previews gemaskeerd getoond.
Database credential
Een database secret beschrijft toegang tot een database: naam, user, password en connectie-URL. Dit is gevoeliger dan een normale instelling omdat het directe datatoegang kan geven. Volgens GitOps hoort structurele applicatiedata via een API/service-laag te lopen; zulke credentials mogen alleen gecontroleerd en doelgericht worden ontsloten.
Env group
Een env group is geen enkel geheim maar een set key/value-variabelen. Elke variabele heeft een naam, waarde en value_type van plain of secret. De hele groep wordt encrypted opgeslagen, ook plain waarden, zodat de groep als een compleet runtime/deploymentpakket kan worden opgehaald.
Hoe zijn ze opgeslagen?
De secret-store gebruikt een publiek deel en een encrypted deel. Het publieke deel bevat metadata en previews: id, type, name, description, preview, previews, created_at en updated_at. Het encrypted deel staat in encrypted_payload en begint met fernet:. De master key uit HERMES_LLM_ROUTER_MASTER_KEY wordt gebruikt om die payload server-side te decrypten.
Router consumer API keys staan apart in api_keys. De authentieke lookup gebeurt via key_hash; key_prefix is alleen herkenning in UI/logs. Wanneer een raw key nog beschikbaar is voor viewkeys/copy, staat die encrypted in raw_key, niet als plaintext.
Hoe vraag je ze op?
Gebruik voor beheer de admin endpoints en voor machine-to-machine ontsluiting de /api/secrets endpoints met master key. Vraag bij voorkeur op type en naam op, bijvoorbeeld /api/secrets/by-name/OpenRouter productie?type=api_key, zodat een consumer geen lijst hoeft te parsen. Gebruik volledige waarden alleen server-side; browserclients en gewone frontends horen geen master key te krijgen.
Swagger voor alle API's
Onderstaande Swagger UI gebruikt dezelfde live OpenAPI-specificatie als /docs. FastAPI genereert deze uit de actuele routes en Pydantic requestmodellen, waardoor nieuwe of gewijzigde endpoints hier automatisch zichtbaar worden.