Docs

Bienvenue

Cette documentation présente comment intégrer un agent Findora: clés API, endpoints, webhooks et bonnes pratiques.

Ce que vous pouvez faire

  • • Envoyer des messages à un agent et lire les réponses
  • • Ajouter des fichiers pour enrichir le contexte
  • • Suivre les sessions et recevoir des webhooks d'événements
Auth

Authentification

Utilisez une clé API secrète via l'entête Bearer. Ne l'exposez jamais côté client.

Entêtes

Authorization: Bearer <VOTRE_CLE_API>
Content-Type: application/json

Bonnes pratiques

  • • Variables d'environnement (FINDORA_API_KEY)
  • • Clés distinctes par environnement (dev, staging, prod)
  • • Rotation régulière, révocation immédiate en cas d'exposition
  • • Jamais côté navigateur: proxifiez depuis votre backend

Exemples

cURL
curl -X POST https://api.findora.ai/v1/messages \
  -H "Authorization: Bearer $FINDORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agt_123","sessionId":"sess_abc","content":"Bonjour"}'
JavaScript
await fetch('https://api.findora.ai/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FINDORA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agt_123',
    sessionId: 'sess_abc',
    content: 'Bonjour'
  }),
});
Quickstart

Votre premier message

Envoyez un message à un agent et obtenez une réponse en quelques lignes.

  1. Créer un agent dans Findora et récupérer une clé API.
  2. Appeler l'endpoint POST /v1/messages avec agentId, sessionId et content.
  3. Lire la réponse JSON (answer, status).
cURL
curl -X POST https://api.findora.ai/v1/messages \
  -H "Authorization: Bearer $FINDORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_123",
    "sessionId": "sess_abc",
    "content": "Bonjour"
  }'
JavaScript
const res = await fetch('https://api.findora.ai/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FINDORA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agt_123',
    sessionId: 'sess_abc',
    content: 'Bonjour'
  }),
});
const data = await res.json();
API

Agents

Créer, configurer et gérer vos agents IA.

GET /v1/agents

Liste tous vos agents disponibles.

Réponse
[
  {
    "id": "agt_123",
    "name": "Agent Commercial",
    "status": "active",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

POST /v1/agents

Créer un nouvel agent.

Requête
{
  "name": "Mon Agent",
  "instructions": "Tu es un assistant commercial...",
  "model": "gpt-4",
  "temperature": 0.7
}
Réponse
{
  "id": "agt_456",
  "name": "Mon Agent",
  "status": "active"
}

GET /v1/agents/:id

Récupérer les détails d'un agent spécifique.

Réponse
{
  "id": "agt_123",
  "name": "Agent Commercial",
  "instructions": "...",
  "model": "gpt-4",
  "temperature": 0.7,
  "status": "active"
}

PATCH /v1/agents/:id

Mettre à jour la configuration d'un agent.

Requête
{
  "name": "Nouveau nom",
  "temperature": 0.5
}
Réponse
{
  "id": "agt_123",
  "name": "Nouveau nom",
  "temperature": 0.5
}

DELETE /v1/agents/:id

Supprimer un agent (action irréversible).

Réponse
{
  "deleted": true,
  "id": "agt_123"
}
API

Messages

Envoyer un message à un agent et récupérer la réponse structurée.

POST /v1/messages

Requête
{
  "agentId": "agt_123",
  "sessionId": "sess_abc",
  "content": "Bonjour"
}
Réponse
{
  "id": "msg_001",
  "sessionId": "sess_abc",
  "status": "completed",
  "answer": "Bonjour, comment puis‑je aider ?"
}
API

Fichiers

Uploader un fichier pour le contexte: PDF, image, tableur.

POST /v1/files

Requête
Content-Type: multipart/form-data
file=@mon.pdf
Réponse
{
  "id": "file_001",
  "status": "ready"
}
API

Sessions

Lister les sessions ouvertes et fermer une session quand elle n'est plus utile.

GET /v1/sessions

Réponse
[
  {
    "id": "sess_abc",
    "createdAt": "..."
  }
]

POST /v1/sessions/close

Requête
{
  "sessionId": "sess_abc"
}
Réponse
{
  "ok": true
}
API

Webhooks

Recevez des notifications en temps réel sur les événements de vos agents.

Configuration

Configurez une URL de webhook dans votre dashboard pour recevoir les événements.

Structure d'un événement
{
  "event": "message.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_001",
    "sessionId": "sess_abc",
    "agentId": "agt_123",
    "status": "completed"
  }
}

Types d'événements

message.created

Un nouveau message a été créé

message.completed

L'agent a terminé de répondre

message.failed

Une erreur s'est produite lors du traitement

session.created

Une nouvelle session a été ouverte

session.closed

Une session a été fermée

file.uploaded

Un fichier a été uploadé avec succès

Sécurité

Chaque webhook inclut une signature HMAC dans l'entête X-Findora-Signature pour vérifier l'authenticité.

Vérification (Node.js)
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}
Référence

Codes d'erreur

Comprendre et gérer les erreurs de l'API Findora.

Structure d'erreur

{
  "error": {
    "code": "invalid_request",
    "message": "Le champ 'agentId' est requis",
    "param": "agentId",
    "type": "validation_error"
  }
}

Codes HTTP

200 OK

La requête a réussi

400 Bad Request

Paramètres invalides ou manquants

401 Unauthorized

Clé API invalide ou expirée

403 Forbidden

Accès refusé à cette ressource

404 Not Found

Ressource introuvable

429 Too Many Requests

Limite de taux dépassée

500 Internal Server Error

Erreur serveur interne

Codes d'erreur spécifiques

Code Description
invalid_api_key La clé API fournie est invalide
agent_not_found L'agent spécifié n'existe pas
session_expired La session a expiré (>24h d'inactivité)
file_too_large Le fichier dépasse la taille maximale (50MB)
rate_limit_exceeded Trop de requêtes en peu de temps
quota_exceeded Quota mensuel de messages dépassé
Référence

Limites & Quotas

Comprendre les limites d'utilisation de l'API.

Rate Limiting

Nombre maximum de requêtes par période de temps.

60
requêtes / minute
1000
requêtes / heure
50k
requêtes / jour

Les entêtes de réponse incluent: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Tailles maximales

Message texte 32,000 caractères
Upload fichier 50 MB
Messages par session 1,000 messages
Durée de session 24 heures