{ "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.", "audit:read": "Audit-Log der Organisation lesen (GET /v1/audit-events) — für SIEM und Prüfung. Nur Service-Keys." } }, "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 Budget dieses Keys ist aufgebraucht — ein erneuter Versuch hilft erst, wenn wieder Budget verfügbar 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 Budget dieses Keys ist aufgebraucht — ein erneuter Versuch hilft erst, wenn wieder Budget verfügbar 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" } ] } }, "/v1/audit-events": { "get": { "operationId": "auditEvents", "summary": "Audit-Log abrufen", "tags": [ "App-API" ], "security": [ { "bearerAuth": [] } ], "x-futureway-scope": "audit:read", "x-futureway-key-kinds": [ "service" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "5b1f7a62-3c52-4d5e-9a0f-0d3c7ac5d2f1", "created_at": "2026-10-01T10:00:00.000Z", "action": "member.role_changed", "category": "member", "actor": { "type": "user", "id": "db72417d-eaa4-4bef-95df-127c54d98753", "name": "Erika Beispiel", "email": "erika@example.org", "key_id": null }, "targets": [ { "key": "target_user_id", "kind": "user", "id": "37a2e31e-da2e-4b45-ad2c-907b42ec7668", "name": "Max Beispiel", "email": "max@example.org" } ], "details": { "target_user_id": "37a2e31e-da2e-4b45-ad2c-907b42ec7668", "from": "member", "to": "manager" }, "origin": { "ip_prefix": "203.0.113.0/24", "user_agent_summary": "Chrome · Windows" } } ], "next_cursor": "2026-10-01T10:00:00.000000Z|5b1f7a62-3c52-4d5e-9a0f-0d3c7ac5d2f1" } } } }, "400": { "description": "invalid_body: Der Request-Body entspricht nicht dem Schema des Endpunkts." }, "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. · 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." } }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nur Einträge ab diesem Zeitpunkt (ISO 8601, inklusive)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nur Einträge bis zu diesem Zeitpunkt (ISO 8601, inklusive)." }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nur Einträge, die diese Person ausgelöst hat." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auth", "security", "sso", "domain", "scim", "member", "group", "share", "api_key", "billing", "automation", "governance", "learning", "org", "studio", "connection", "export", "audit" ] }, "description": "Nur Einträge dieses Bereichs." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nur Einträge dieser Aktion, z. B. member.role_changed." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Freitext über Aktionsnamen und die Namen der beteiligten Personen und Gruppen." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Der Wert next_cursor der vorherigen Antwort — liefert die nächste Seite." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Einträge je Seite, 1 bis 200 (Standard 50)." } ], "servers": [ { "url": "https://api.futureway.ai" } ] } } } }