> ## Documentation Index > Fetch the complete documentation index at: https://docs.fim.ai/llms.txt > Use this file to discover all available pages before exploring further. # API-Übersicht > Erste Schritte mit der FIM One REST API Die API-Referenzdokumentation ist derzeit nur in **Englisch** verfügbar. Wenn Sie diese Seite in einer anderen Sprache anzeigen, wechseln Sie bitte zur englischen Version — die vollständige Liste der API-Endpunkte wird in der linken Seitenleiste angezeigt. FIM One bietet eine REST API für programmgesteuerten Zugriff auf KI-Agenten, Gespräche, Wissensdatenbanken und mehr. ## Basis-URL ``` https://your-domain.com/api ``` ## Authentifizierung Alle API-Anfragen erfordern eine Authentifizierung über einen API-Schlüssel oder JWT-Token. ### API-Schlüssel verwenden Fügen Sie Ihren API-Schlüssel in den `Authorization`-Header ein: ```bash theme={null} curl -H "Authorization: Bearer fim_your_api_key_here" \ https://your-domain.com/api/agents ``` ### JWT-Token verwenden Für SSE-Streaming-Endpunkte (`/api/react` und `/api/dag`) können Sie das Token stattdessen im Request-Body übergeben: ```json theme={null} { "q": "What's the weather today?", "token": "your_jwt_token_here" } ``` Siehe [Authentifizierung](/api/authentication) für detaillierte Setupanweisungen. ## Antwortformat ### Erfolgreiche Antwort Alle erfolgreichen API-Antworten folgen dieser Struktur: ```json theme={null} { "success": true, "data": { "id": "conv_123abc", "title": "My Conversation", "created_at": "2024-01-15T10:30:00Z" } } ``` ### Fehlerantwort Fehlerantworten enthalten einen Fehlercode und eine für Menschen lesbare Nachricht: ```json theme={null} { "success": false, "error": "conversation_not_found", "message": "The conversation does not exist or has been deleted" } ``` ### Paginierte Antworten List-Endpunkte geben paginierte Ergebnisse zurück: ```json theme={null} { "items": [ { "id": "item_1", "name": "First Item" }, { "id": "item_2", "name": "Second Item" } ], "total": 42, "page": 1, "size": 20, "pages": 3 } ``` ## Streaming (Server-Sent Events) Chat-Endpunkte (`POST /api/react` und `POST /api/dag`) geben Server-Sent Events für Echtzeit-Streaming zurück. Jedes Event hat ein `type`-Feld, das seinen Inhalt angibt: | Event-Typ | Beschreibung | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `step` | ReAct-Reasoning-Schritt (Tool-Aufrufe, Denken). Für Modelle mit erweitertem Denken (Claude, o-Serie, DeepSeek-R1) enthält `thinking_delta`-Inhalte in Echtzeit während Tool-Entscheidungsphasen | | `step_progress` | DAG-Schrittfortschritt (gestartet/Iteration/abgeschlossen). Kann `thinking_delta`-Inhalte enthalten, wenn der zugrunde liegende Agent Reasoning-Token streamt | | `phase` | Pipeline-Phasenübergang (Planung/Ausführung/Analyse) | | `compact` | Kontext-Komprimierung aufgetreten | | `answer` | Gestreamter Antworttext (Start/Delta/Fertig) | | `done` | Endgültiges Ergebnis-Payload | | `suggestions` | Vorgeschlagene Anschlussfragen | | `title` | Automatisch generierter Gesprächstitel | | `end` | Stream-Terminator (immer zuletzt) | ### SSE-Stream-Beispiel ``` event: step data: {"type": "tool_call", "tool": "search", "input": "Paris weather"} event: answer data: {"type": "delta", "text": "Based on current data, "} event: answer data: {"type": "delta", "text": "Paris has pleasant weather."} event: done data: {"answer": "Based on current data, Paris has pleasant weather.", "tokens": 128} event: suggestions data: ["What about tomorrow's forecast?", "Compare with other European cities"] event: end data: {} ``` ### Cursor-basierte Wiederaufnahme Jedes SSE-Event trägt eine monotone `cursor`-Ganzzahl, die auf das Gespräch beschränkt ist. Clients sollten den höchsten angetroffenen Cursor verfolgen. Wenn die Verbindung während eines Durchlaufs abbricht (Netzwerkfehler, Proxy-Timeout, Server-Neustart), kann der Client sich erneut abonnieren, ohne den Agenten erneut auszuführen: ```http theme={null} POST /api/chat/resume Content-Type: application/json Authorization: Bearer { "conversation_id": "", "cursor": 42 } ``` Die Antwort ist ein SSE-Stream, der zwischengespeicherte Events mit `cursor > 42` erneut abspielt und mit einem Terminal-`event: resume_done`-Frame endet. Übergeben Sie `cursor: -1`, um eine vollständige Wiederaufnahme von Anfang an anzufordern. Fehlerantworten: * `404 conversation_not_found` — Gesprächs-ID ist ungültig oder gehört nicht dem authentifizierten Benutzer * `404 no_recent_assistant_message` — Gespräch hat keine persistierte Assistent-Runde zum Fortsetzen (z. B. ein brandneues Gespräch ohne Benutzernachrichten) * `400 invalid_cursor` — Cursor ist keine nicht-negative Ganzzahl oder `-1` Die Referenz-Frontend-Implementierung (`useSseResume` Hook im Playground) versucht Netzwerktrennungen automatisch mit exponentiellem Backoff erneut (300ms → 1s → 3s, max. 3 Versuche) und unterscheidet benutzerinitiierte Abbrüche von Netzwerkfehlern, um unbeabsichtigte Wiederverbindungen zu vermeiden. Siehe die `playground-page.tsx`-Integration für das vollständige Muster. Die Wiederaufnahme ist zustandslos — sie spielt Events aus dem gespeicherten `sse_events`-Array der Assistent-Nachricht erneut ab. Wenn der Durchlauf des Agenten unterbrochen wurde, bevor eine Assistent-Nachricht persistiert wurde (z. B. ein Absturz vor `done`), wird der verwaiste `tool_use`-Block automatisch durch `DbMemory._repair_dangling_tool_calls` im nächsten Durchlauf repariert. Synthetische `tool_result`-Zeilen werden mit `metadata_.synthetic=true` und `metadata_.reason="interrupted"` für Audit persistiert. ## Ratenbegrenzung Die Ratenbegrenzung pro Schlüssel ist für eine zukünftige Version geplant. Derzeit gibt es keine durchgesetzten Anfragelimits pro Schlüssel, aber bitte nutzen Sie die API verantwortungsvoll. ## Pagination List-Endpunkte unterstützen Pagination über Abfrageparameter: ```bash theme={null} curl "https://your-domain.com/api/conversations?page=2&size=50" \ -H "Authorization: Bearer fim_your_api_key_here" ``` Parameter: * `page` (Standard: 1) — Seitennummer, beginnend bei 1 * `size` (Standard: 20) — Elemente pro Seite, max. 100 ## Zeitstempel Alle Zeitstempel sind im ISO 8601-Format mit UTC-Zeitzone: ```json theme={null} { "created_at": "2024-01-15T10:30:45.123456Z", "updated_at": "2024-01-15T14:22:10.654321Z" } ``` ## Fehlercodes Häufige Fehlercodes und ihre Bedeutungen: | Fehlercode | HTTP-Status | Bedeutung | | --------------------- | ----------- | --------------------------------------------------- | | `unauthorized` | 401 | Ungültige oder fehlende Authentifizierung | | `forbidden` | 403 | Benutzer hat keine Berechtigung für diese Ressource | | `not_found` | 404 | Ressource existiert nicht | | `bad_request` | 400 | Ungültige Anfrageparameter | | `rate_limit_exceeded` | 429 | Zu viele Anfragen (geplant) | | `internal_error` | 500 | Serverfehler | ## API-Spielplatz Jede Endpunkt-Seite enthält einen interaktiven API-Spielplatz, in dem Sie: * Anfragen direkt von Ihrem Browser aus testen können * Echte Antworten anzeigen können * Anfrage-Code in mehreren Sprachen kopieren können * Sich mit Ihrem API-Schlüssel authentifizieren können Der API-Spielplatz führt Anfragen von Ihrem Browser aus aus, daher stellen Sie sicher, dass Ihr API-Schlüssel über entsprechende CORS-Berechtigungen verfügt (normalerweise standardmäßig für Same-Origin-Anfragen aktiviert). ## SDK-Verfügbarkeit Obwohl die FIM One API vollständig REST-basiert ist, sind SDKs in beliebten Sprachen verfügbar (oder in Kürze verfügbar): * **Python**: In Kürze verfügbar * **JavaScript/TypeScript**: In Kürze verfügbar * **Go**: In Kürze verfügbar ## Versionierung Die aktuelle API-Version ist `v0.8.0`. Die Version ist nicht im URL-Pfad enthalten; Breaking Changes werden durch Major-Version-Bumps und eine Migrationsfrist signalisiert. ## Unterstützung Bei API-Problemen oder Fragen: * **Dokumentation**: Siehe detaillierte Leitfäden zu jedem Endpunkt * **GitHub Issues**: Melden Sie Fehler unter [https://github.com/fim-ai/fim-one/issues](https://github.com/fim-ai/fim-one/issues) * **Discord Community**: Treten Sie unserer Community bei, um zu diskutieren