{ "openapi": "3.1.0", "info": { "title": "FutureWay AI API", "version": "v1", "description": "OpenAI-kompatible Inferenz-API auf EU-gehosteten Modellen und App-API mit Scopes: Schnellstart, Authentifizierung, Fehler, Rate-Limits, Referenz mit Beispielen in curl, Python und JavaScript." }, "servers": [ { "url": "https://api.futureway.ai" } ], "tags": [ { "name": "Inference" }, { "name": "App-API" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (`sk-fw-…`) from /settings/api. Server-to-server only — browser requests are rejected." } }, "x-futureway-scopes": { "inference": "Inferenz-API: Chat-Completions, Embeddings, Modellliste.", "agents:run": "Agenten ausführen (App-API, folgt).", "knowledge:read": "Wissensbereiche auflisten, Dateien lesen, Suche und Graph-Abfragen (App-API, folgt).", "knowledge:write": "Dateien in Wissensbereiche hochladen, ersetzen und löschen (folgt).", "agents:manage": "Agenten anlegen und ändern (folgt).", "prompts": "Prompts anlegen, ändern und löschen (folgt).", "usage:export": "Aggregierte Nutzungsdaten exportieren — nie Chat-Inhalte (folgt).", "audit:read": "Audit-Log und Nutzungsprotokoll der Organisation lesen (folgt).", "members:invite": "Mitglieder einladen und deaktivieren (folgt)." } }, "paths": { "/v1/chat/completions": { "post": { "operationId": "chatCompletions", "summary": "Chat-Completion erzeugen", "tags": [ "Inference" ], "security": [ { "bearerAuth": [] } ], "x-futureway-scope": "inference", "x-futureway-key-kinds": [ "personal", "service" ], "x-futureway-streaming": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "chatcmpl-8f3c…", "object": "chat.completion", "created": 1757750400, "model": "futureway-smart", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Die Hauptstadt von Frankreich ist Paris." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 14, "completion_tokens": 9, "total_tokens": 23 } } } } }, "400": { "description": "invalid_request_error: Anfrage ungültig (fehlende Pflichtfelder, unbekannter Parameter, Body zu groß)." }, "401": { "description": "unauthorized: Kein, ungültiger oder widerrufener API-Key." }, "404": { "description": "model_not_found: Unbekannte Modell-ID oder ein Modell, das dieser Key nicht ansprechen darf." }, "429": { "description": "rate_limit_error: Zu viele Anfragen im Zeitfenster; retry-after nennt die Wartezeit. · budget_exceeded: Das Nutzungskontingent der Organisation ist aufgebraucht — kein Retry hilft, bis das Fenster zurückgesetzt ist." }, "503": { "description": "service_unavailable: Das Modell ist vorübergehend nicht erreichbar — mit Backoff wiederholen." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Modell-Alias, z. B. futureway-smart." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "description": "Wer spricht." }, "content": { "type": "string", "description": "Text der Nachricht; Bilder als Content-Parts wie bei OpenAI, wenn das Modell Bilder kann." } }, "required": [ "role", "content" ] }, "description": "Die Konversation in Reihenfolge; mindestens eine Nachricht." }, "stream": { "type": "boolean", "description": "Antwort als Server-Sent Events, sobald Tokens entstehen." }, "temperature": { "type": "number", "description": "Zufälligkeit 0–2; Standard des Modells, wenn weggelassen." }, "max_tokens": { "type": "integer", "description": "Obergrenze für die Antwortlänge." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Werkzeugdefinitionen im OpenAI-Function-Format." }, "tool_choice": { "type": "string", "description": "auto, none oder ein bestimmtes Werkzeug." }, "response_format": { "type": "object", "description": "Strukturierte Ausgabe, z. B. { \"type\": \"json_object\" }." } }, "required": [ "model", "messages" ] }, "example": { "model": "futureway-smart", "messages": [ { "role": "user", "content": "Was ist die Hauptstadt von Frankreich?" } ] } } } }, "servers": [ { "url": "https://api.futureway.ai" } ] } }, "/v1/embeddings": { "post": { "operationId": "embeddings", "summary": "Embeddings berechnen", "tags": [ "Inference" ], "security": [ { "bearerAuth": [] } ], "x-futureway-scope": "inference", "x-futureway-key-kinds": [ "personal", "service" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0123, -0.0456, "…" ] } ], "model": "futureway-embed", "usage": { "prompt_tokens": 4, "total_tokens": 4 } } } } }, "400": { "description": "invalid_request_error: Anfrage ungültig (fehlende Pflichtfelder, unbekannter Parameter, Body zu groß)." }, "401": { "description": "unauthorized: Kein, ungültiger oder widerrufener API-Key." }, "404": { "description": "model_not_found: Unbekannte Modell-ID oder ein Modell, das dieser Key nicht ansprechen darf." }, "429": { "description": "rate_limit_error: Zu viele Anfragen im Zeitfenster; retry-after nennt die Wartezeit. · budget_exceeded: Das Nutzungskontingent der Organisation ist aufgebraucht — kein Retry hilft, bis das Fenster zurückgesetzt ist." }, "503": { "description": "service_unavailable: Das Modell ist vorübergehend nicht erreichbar — mit Backoff wiederholen." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Embedding-Alias, z. B. futureway-embed." }, "input": { "type": "string", "description": "Der einzubettende Text." } }, "required": [ "model", "input" ] }, "example": { "model": "futureway-embed", "input": "Dein Text hier." } } } }, "servers": [ { "url": "https://api.futureway.ai" } ] } }, "/v1/models": { "get": { "operationId": "models", "summary": "Modelle auflisten", "tags": [ "Inference" ], "security": [ { "bearerAuth": [] } ], "x-futureway-scope": "inference", "x-futureway-key-kinds": [ "personal", "service" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "futureway-fast", "object": "model", "owned_by": "futureway" }, { "id": "futureway-smart", "object": "model", "owned_by": "futureway" }, { "id": "futureway-bigthink", "object": "model", "owned_by": "futureway" }, { "id": "futureway-embed", "object": "model", "owned_by": "futureway" } ] } } } }, "401": { "description": "unauthorized: Kein, ungültiger oder widerrufener API-Key." }, "429": { "description": "rate_limit_error: Zu viele Anfragen im Zeitfenster; retry-after nennt die Wartezeit." } }, "servers": [ { "url": "https://api.futureway.ai" } ] } }, "/v1/me": { "get": { "operationId": "me", "summary": "Eigenen Key prüfen", "tags": [ "App-API" ], "security": [ { "bearerAuth": [] } ], "x-futureway-scope": "inference", "x-futureway-key-kinds": [ "personal", "service" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "key": { "id": "db72417d-eaa4-4bef-95df-127c54d98753", "kind": "service", "scopes": [ "inference", "knowledge:read" ], "expires_at": "2026-12-13T07:47:06.057Z" }, "organization": { "id": "37a2e31e-da2e-4b45-ad2c-907b42ec7668", "plan": "advanced" } } } } }, "401": { "description": "unauthorized: Kein, ungültiger oder widerrufener API-Key. · key_expired: Der Key ist abgelaufen — neuen Key anlegen." }, "403": { "description": "scope_missing: Der Key trägt nicht den Scope, den dieser Endpunkt verlangt. · academy_only: Dieses Konto hat nur Zugang zur Akademie, nicht zur Plattform. · browser_request_rejected: Die Anfrage sieht wie ein Browser aus (Origin, Fetch-Metadaten oder Session-Cookie)." }, "429": { "description": "rate_limit_error: Zu viele Anfragen im Zeitfenster; retry-after nennt die Wartezeit." } }, "servers": [ { "url": "https://api.futureway.ai" } ] } } } }