Zum Hauptinhalt springen

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.

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:
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:
{
  "q": "What's the weather today?",
  "token": "your_jwt_token_here"
}
Siehe Authentifizierung für detaillierte Setupanweisungen.

Antwortformat

Erfolgreiche Antwort

Alle erfolgreichen API-Antworten folgen dieser Struktur:
{
  "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:
{
  "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:
{
  "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-TypBeschreibung
stepReAct-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_progressDAG-Schrittfortschritt (gestartet/Iteration/abgeschlossen). Kann thinking_delta-Inhalte enthalten, wenn der zugrunde liegende Agent Reasoning-Token streamt
phasePipeline-Phasenübergang (Planung/Ausführung/Analyse)
compactKontext-Komprimierung aufgetreten
answerGestreamter Antworttext (Start/Delta/Fertig)
doneEndgültiges Ergebnis-Payload
suggestionsVorgeschlagene Anschlussfragen
titleAutomatisch generierter Gesprächstitel
endStream-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:
POST /api/chat/resume
Content-Type: application/json
Authorization: Bearer <jwt>

{
  "conversation_id": "<uuid>",
  "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:
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:
{
  "created_at": "2024-01-15T10:30:45.123456Z",
  "updated_at": "2024-01-15T14:22:10.654321Z"
}

Fehlercodes

Häufige Fehlercodes und ihre Bedeutungen:
FehlercodeHTTP-StatusBedeutung
unauthorized401Ungültige oder fehlende Authentifizierung
forbidden403Benutzer hat keine Berechtigung für diese Ressource
not_found404Ressource existiert nicht
bad_request400Ungültige Anfrageparameter
rate_limit_exceeded429Zu viele Anfragen (geplant)
internal_error500Serverfehler

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
  • Discord Community: Treten Sie unserer Community bei, um zu diskutieren