Ottili AI API

Die Ottili AI API ist die öffentliche, versionierte Schnittstelle, um auf Ottili AI zuzugreifen. Sie ermöglicht es Ihrem Backend, denselben Assistenten, dieselbe Modellauswahl, Tool-Ausführung und Credit-Abrechnung zu nutzen wie der im Produkt integrierte Assistent — ohne das Dashboard anzufassen.

Dies ist der Einstiegspunkt in die AI-API-Dokumentation. Jeder Abschnitt unten verweist auf eine eigene Referenz.

Basis-URL und Kompatibilität

Die AI-API wird über den öffentlichen Ottili-ONE-Entwickler-Host bereitgestellt:

https://api.ai.ottili.one/v1

Sie gehört zur selben öffentlichen, versionierten Entwickler-Oberfläche wie die Ottili ONE Public Developer API und teilt daher deren Konventionen:

• Bearer-Authentifizierung (Service-API-Key oder JWT).
• Scope-basierter Zugriff.
• Unternehmens- und Workspace-Kontext aus verifizierter Mitgliedschaft, nie aus einem Roh-Mandanten-Header.
• Standard-HTTP-Statuscodes mit maschinenlesbaren Fehlerkörpern.
• Pro Fenster zurückgegebene Rate Limits in Response-Headern.

Die autoritative Liste verfügbarer AI-Endpunkte für Ihr Unternehmen und Ihren Tarif liefert der live API-Metadata-Endpunkt. Interne Unified-API-Routen und Dashboard-Routen sind hier bewusst nicht dokumentiert.

Authentifizierung

Jede Anfrage authentifiziert sich über den Authorization-Header:

Authorization: Bearer ott_your_api_key_here

Zwei Anmeldetypen werden akzeptiert:

• Service-API-Keys* — in Ottili Auth erstellt, mit ott_ präfixiert, nur einmal bei Erstellung sichtbar, serverseitig gehasht gespeichert.
• JWT-Bearer-Tokens* — von Ottili Auth für Benutzersitzungen ausgestellt.

API-Keys sind an eine verifizierte Benutzermitgliedschaft gebunden und tragen Scopes. Ein fehlender oder unzureichender Scope führt zu einem geschlossenen Fehler.

Mandantenkontext

AI-Anfragen laufen immer in einem Unternehmen und Workspace. Dieser Kontext wird automatisch*

aus der verifizierten Mitgliedschaft des gesendeten API-Schlüssels oder JWT aufgelöst — du

übermittelst keine* Tenant- oder Company-Header. Rohe Company-ID-Header werden ignoriert.

Inaktive, gesperrte oder archivierte Unternehmen werden abgelehnt, was

permission_error / model_not_found (HTTP 403/404) über den normalisierten

Fehler-Körper liefert. Rohe Company-ID-Header werden ignoriert.

Gateway-Status & Diagnose

Sobald authentifiziert, lässt sich der eigene Boundary-Status ohne Inference-Call

prüfen. Die kundensichere Status-Oberfläche liefert nur den Kontext Ihres Unternehmens

— niemals Provider-Secrets, rohe Upstream-Slugs oder Daten anderer Mandanten:

curl "https://api.ai.ottili.one/v1/gateway/status" \
  -H "Authorization: Bearer otk_live_xxx"

Die Antwort enthält einen einzelnen state (configured | degraded | blocked |

error), Ihr verfügbares Guthaben (balance − reserved, nie die rohen reservierten

Interna), den Modellkatalog mit Verfügbarkeit, die Richtlinie Ihres Keys (Scopes,

erlaubte Modelle, rpm/tpm, Monatsbudget) und die Preis-Aktualität (pricing_version).

Ein blocked-State bedeutet, dass Ihr Key von einem Administrator blockiert oder

widerrufen wurde; ein error-State weist auf einen fehlgeschlagenen Credit-Abruf hin.

Sie können zudem prüfen, ob ein Idempotency-Key noch belegt ist (nur operative

Sicht — niemals Request-Bodies, Prompts oder Provider-Interna):

curl "https://api.ai.ottili.one/v1/gateway/idempotency/<ihr-idempotency-key>" \
  -H "Authorization: Bearer otk_live_xxx"

Diese Diagnose-Endpunkte gehören zur öffentlichen Boundary, dokumentiert in dieser Referenz, und sind live auf api.ai.ottili.one/v1 (Router via T-Q3-AI-0013 eingehängt). Falls eine ältere Installation 404 für /v1/gateway/status liefert, stammt sie aus vor jenem Mount — die Kern-Boundary (Auth, Idempotency, blocked-key-Enforcement auf /v1/chat/completions und /v1/responses) ist davon unabhängig live.

Schnellstart

curl -X POST "https://api.ai.ottili.one/v1/chat/completions" \
  -H "Authorization: Bearer otk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ottili/vale-1.2",
    "messages": [
      { "role": "user", "content": "Fasse die offenen Bestellungen dieses Kunden zusammen." }
    ]
  }'

Das Feld model akzeptiert eine Modell-ID oder den Router auto, der anhand Anfrage, Tarif und Verfügbarkeit ein Modell wählt.

Beispiele in dieser Referenz

Die folgenden Referenzen gehen tiefer auf jeden Teil des Vertrags ein:

• Modelle & Verfügbarkeit* — wie Routing und Verfügbarkeit funktionieren.
• Credits & Nutzungsfelder* — wie AI-Nutzung gemessen und gemeldet wird.
• Rate Limits* — Fenster, Header und Backoff.
• Streaming* — tokenweises Server-Sent-Streaming.
• Tool-Calls* — wie der Assistent Plattformaktionen anfragt.
• Strukturierte Ausgaben* — JSON-Schema-konforme Antworten.
• Fehler* — Statuscodes und maschinenlesbare Fehlercodes.
• Caching* — was sicher zwischengespeichert werden darf.

Status

Die Ottili AI API befindet sich im Public Beta. Fähigkeiten, Felder und Limits können sich weiterentwickeln; der live API-Metadata-Endpunkt ist die Quelle der Wahrheit für den aktuellen Vertrag.