Developers

Öffentliche API im Überblick

Was die öffentliche Ottili ONE API ist, wo sie erreichbar ist, wie das Deny-by-Default-Modell, die Authentifizierung, Ratelimits und der dokumentierte OpenAPI-Vertrag funktionieren – mit klar getrennten Live-, Beta- und geplanten Zuständen.

Überblick

Die öffentliche API* ist der einzige dokumentierte, externe Einstiegspunkt für Ottili ONE. Sie läuft unter der Basis-URL https://api.ottili.one und ist als Deny-by-Default-Grenze* gebaut: Nur die Pfade, die ausdrücklich in der öffentlichen Allowlist stehen, sind erreichbar. Alles andere beantwortet die Kante (Caddy-Edge) mit 403 Forbidden.

Die Grenze leitet erlaubte Anfragen an die Unified API (Backend, Port 8100) weiter. Interne, Admin-, Debug-, Datenbank- und lokale Routen sind aus dem öffentlichen Vertrag entfernt.

Status der öffentlichen API

Ottili ONE kennzeichnet jede Route und jedes Feature mit einem Reifegrad. Für die öffentliche API gilt:

Live* — heute über api.ottili.one erreichbar und unterstützt.
Beta* — in Vorabversion verfügbar (z. B. das Python-SDK ottili-sdk).
In Entwicklung / Geplant* — im bereinigten OpenAPI-Vertrag beschrieben, aber noch nicht vollständig über das öffentliche Gateway ausgeliefert.

Erreichbare Endpunkte (Live)

Heute sind über die öffentliche Kante folgende Routen freigegeben:

Methode	Pfad	Auth	Hinweis
`GET`	`/api/v1/status`	keine	Öffentlicher Statusendpunkt (z. B. für Worker-Health-Checks).
`POST`	`/api/v1/platform/public/contact`	keine	Kontakt-/Demo-/Vertriebsformulare aus dem Website-Worker; ratelimitiert.
`POST`	`/api/v1/platform/billing/webhooks/stripe`	Signatur	Eingehender Stripe-Billing-Webhook (signaturverifiziert).
`POST`	`/api/v1/platform/billing/stripe/webhook`	Signatur	Alternativer Stripe-Webhook-Pfad; als veraltet markiert.
`POST`	`/coder/token`	JWT (OIDC)	Ottili Coder OIDC-Broker: GitHub-OIDC-Token wird gegen Plattform-Modell-Credentials getauscht.
`POST`	`/coder/progress`	JWT (OIDC)	Fortschritts-Callback des Coder OIDC-Brokers (GitHub Actions).

Die Webhook- und OIDC-Routen sind interne* Routen (eingehende Webhooks bzw. Runner-Broker), keine entwicklerseitig aufzurufenden Endpunkte. Die öffentlich aufrufbaren, nicht authentifizierten Endpunkte sind GET /api/v1/status und POST /api/v1/platform/public/contact.

Authentifizierung

Die Grenze unterstützt drei Auth-Modi:

Keine (public)* — öffentliche Endpunkte wie Status und Kontakt erfordern kein Token.
Signatur* — Stripe signiert Webhook-Payloads; die Signatur wird im Handler verifiziert.
JWT (OIDC)* — der Coder OIDC-Broker tauscht ein GitHub-OIDC-Token gegen Plattform-Credentials; das JWT ist die Berechtigung.

Für die geplanten entwicklerseitigen API-Aufrufe ist die Authentifizierung über BearerAuth (JWT/OAuth2) und ApiKeyAuth (Entwickler-API-Schlüssel) im OpenAPI-Vertrag dokumentiert – siehe [Öffentliche API-Authentifizierung](/docs/public-api-authentication).

Ratelimits

Die Grenze wendet Ratelimits pro Client-IP (rollierendes 60-Sekunden-Fenster) an und kommuniziert sie über die Header X-RateLimit-Limit, X-RateLimit-Remaining und Retry-After:

Standard:* 600 Anfragen / 60 s pro IP.
Kontaktendpunkt:* 10 Anfragen / 60 s pro IP (Spamschutz).

Fehlerformat

Jede Fehlerantwort der Grenze nutzt eine strukturierte Hüllenstruktur:

{
  "ok": false,
  "error": { "code": "VALIDATION_ERROR", "message": "…", "status": 422 },
  "request_id": "req_…"
}

Client-Fehler werden mit 4xx, Server-Fehler mit 5xx gemeldet; request_id erleichtert die Nachverfolgung.

Dokumentierter OpenAPI-Vertrag

Neben den heute live geschalteten Routen veröffentlicht Ottili ONE einen bereinigten OpenAPI-Vertrag*, der die für externe Entwickler freigegebenen Oberflächen beschreibt (Developer-API, Inhalte, Plattform, Business, Module und Integrationen). Intern, Admin-, Debug- und Datenbankrouten sind entfernt. Aufbau und Regenerierung des Vertrags beschreibt [Public API Contract](/docs/public-api-contract).

Die Ausspielung nur* dieses Vertrags über das öffentliche Gateway (statt der vollständigen internen Unified API) ist eine eigene Deployment-Aufgabe. Bis dahin gilt für api.ottili.one das Deny-by-Default-Modell mit der oben gelisteten Live-Allowlist.

Wie weiter?

Lies den [Public API Contract](/docs/public-api-contract) für Aufbau und Regenerierung des Vertrags.
Nutze das [Python-SDK ottili-sdk](/docs/sdk-and-client-libraries) (Beta, aus dem Quellcode).
Verstehe die [Authentifizierung](/docs/public-api-authentication) für kommende Entwickler-API-Aufrufe.
Sieh dir die [Cloud APIs](/docs/cloud-apis) für hostingnahe Schnittstellen an.
Erhalte einen Überblick über [Ottili ONE](/docs/what-is-ottili-one).

War dieser Artikel hilfreich?