Passer au contenu principal

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.

La documentation de référence de l’API est actuellement disponible en anglais uniquement. Si vous consultez cette page dans une autre langue, veuillez basculer vers la version anglaise — la liste complète des points de terminaison de l’API apparaîtra dans la barre latérale gauche.
FIM One fournit une API REST pour un accès programmatique aux agents IA, conversations, bases de connaissances, et bien plus encore.

URL de base

https://your-domain.com/api

Authentification

Toutes les demandes d’API nécessitent une authentification via une clé API ou un jeton JWT.

Utilisation de la clé API

Incluez votre clé API dans l’en-tête Authorization :
curl -H "Authorization: Bearer fim_your_api_key_here" \
  https://your-domain.com/api/agents

Utilisation du jeton JWT

Pour les points de terminaison de streaming SSE (/api/react et /api/dag), vous pouvez transmettre le jeton dans le corps de la requête à la place :
{
  "q": "What's the weather today?",
  "token": "your_jwt_token_here"
}
Consultez Authentification pour des instructions de configuration détaillées.

Format de réponse

Réponse réussie

Toutes les réponses API réussies suivent cette structure :
{
  "success": true,
  "data": {
    "id": "conv_123abc",
    "title": "My Conversation",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Réponse d’erreur

Les réponses d’erreur incluent un code d’erreur et un message lisible par l’homme :
{
  "success": false,
  "error": "conversation_not_found",
  "message": "The conversation does not exist or has been deleted"
}

Réponses Paginées

Les points de terminaison de liste retournent des résultats paginés :
{
  "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)

Les points de terminaison de chat (POST /api/react et POST /api/dag) retournent des Server-Sent Events pour le streaming en temps réel. Chaque événement a un champ type indiquant son contenu :
Type d’événementDescription
stepÉtape de raisonnement ReAct (appels d’outils, réflexion). Pour les modèles avec pensée étendue (Claude, série o, DeepSeek-R1), inclut le contenu thinking_delta en temps réel pendant les phases de décision d’outils
step_progressProgression de l’étape DAG (démarrée/itération/complétée). Peut inclure le contenu thinking_delta lorsque l’agent sous-jacent diffuse les tokens de raisonnement
phaseTransition de phase du pipeline (planification/exécution/analyse)
compactCompaction de contexte effectuée
answerTexte de réponse diffusé (début/delta/terminé)
doneCharge utile du résultat final
suggestionsQuestions de suivi suggérées
titleTitre de conversation généré automatiquement
endTerminateur de flux (toujours dernier)

Flux SSE

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: {}

Reprise basée sur le curseur

Chaque événement SSE porte un entier cursor monotone limité à la conversation. Les clients doivent suivre le curseur le plus élevé observé. Lorsque la connexion s’interrompt en cours de tour (erreur réseau, délai d’attente du proxy, redémarrage du serveur), le client peut se réabonner sans relancer l’agent :
POST /api/chat/resume
Content-Type: application/json
Authorization: Bearer <jwt>

{
  "conversation_id": "<uuid>",
  "cursor": 42
}
La réponse est un flux SSE qui rejoue les événements en cache avec cursor > 42 et se termine par une trame terminale event: resume_done. Passez cursor: -1 pour demander une relecture complète depuis le début. Réponses d’erreur :
  • 404 conversation_not_found — l’id de conversation est invalide ou n’appartient pas à l’utilisateur authentifié
  • 404 no_recent_assistant_message — la conversation n’a pas de tour assistant persisté à partir duquel reprendre (par exemple, une conversation toute nouvelle sans messages utilisateur)
  • 400 invalid_cursor — le curseur n’est pas un entier non-négatif ou -1
L’implémentation frontend de référence (hook useSseResume dans le playground) réessaie automatiquement les déconnexions réseau avec backoff exponentiel (300ms → 1s → 3s, max 3 tentatives) et distingue l’abandon initié par l’utilisateur de l’erreur réseau pour éviter les reconnexions involontaires. Consultez l’intégration playground-page.tsx pour le modèle complet.
La reprise est sans état — elle rejoue à partir du tableau sse_events stocké du message assistant. Si le tour de l’agent a été interrompu avant qu’un message assistant ne soit persisté (par exemple, un crash avant done), le bloc tool_use en suspens est automatiquement réparé par DbMemory._repair_dangling_tool_calls au tour suivant. Les lignes tool_result synthétiques sont persistées avec metadata_.synthetic=true et metadata_.reason="interrupted" à titre d’audit.

Limitation de débit

La limitation de débit par clé est prévue pour une version future. Actuellement, il n’y a pas de limites de requêtes appliquées par clé, mais veuillez utiliser l’API de manière responsable.

Pagination

Les points de terminaison de liste prennent en charge la pagination via les paramètres de requête :
curl "https://your-domain.com/api/conversations?page=2&size=50" \
  -H "Authorization: Bearer fim_your_api_key_here"
Paramètres :
  • page (par défaut : 1) — numéro de page, à partir de 1
  • size (par défaut : 20) — éléments par page, max 100

Horodatages

Tous les horodatages sont au format ISO 8601 avec le fuseau horaire UTC :
{
  "created_at": "2024-01-15T10:30:45.123456Z",
  "updated_at": "2024-01-15T14:22:10.654321Z"
}

Codes d’erreur

Codes d’erreur courants et leurs significations :
Code d’erreurStatut HTTPSignification
unauthorized401Authentification invalide ou manquante
forbidden403L’utilisateur n’a pas les permissions pour cette ressource
not_found404La ressource n’existe pas
bad_request400Paramètres de requête invalides
rate_limit_exceeded429Trop de requêtes (prévu)
internal_error500Erreur serveur

Terrain de jeu API

Chaque page de point de terminaison inclut un terrain de jeu API interactif où vous pouvez :
  • Tester les demandes directement depuis votre navigateur
  • Afficher les réponses réelles
  • Copier le code de demande dans plusieurs langues
  • S’authentifier avec votre clé API
Le terrain de jeu API exécute les demandes depuis votre navigateur, assurez-vous donc que votre clé API dispose des autorisations CORS appropriées (généralement activées par défaut pour les demandes de même origine).

Disponibilité du SDK

Bien que l’API FIM One soit entièrement basée sur REST, des SDK sont disponibles (ou à venir) dans les langages populaires :
  • Python : À venir
  • JavaScript/TypeScript : À venir
  • Go : À venir

Versioning

La version actuelle de l’API est v0.8.0. La version n’est pas incluse dans le chemin d’accès de l’URL ; les modifications incompatibles seront signalées par des augmentations de version majeure et une période de migration.

Support

Pour les problèmes ou questions liés à l’API :
  • Documentation : Consultez les guides détaillés sur chaque endpoint
  • GitHub Issues : Signalez les bugs sur https://github.com/fim-ai/fim-one/issues
  • Communauté Discord : Rejoignez notre communauté pour discuter