Conversations API

Documentation complète de l'API de gestion des conversations dans Devana.ai.

Base URL: https://api.devana.ai Préfixe: /v1/conversations Authentification: API Key requise

📑 Table des matières

Vue d'ensemble
Authentification
Endpoints disponibles
Modèles de données
Fonctionnalités spéciales
Exemples d'intégration
Différences avec l'API publique

Vue d'ensemble

L'API Conversations permet de gérer les conversations existantes avec les agents IA :

Récupération des métriques détaillées (tokens, temps, sources)
Accès à l'historique complet des messages
Suppression sécurisée avec cascade

Note importante : Cette API gère les conversations après leur création. Pour créer de nouvelles conversations, utilisez l'endpoint /v1/chat/completions.

Authentification

Toutes les requêtes nécessitent une clé API dans le header Authorization :

http

Authorization: Bearer YOUR_API_KEY

Les permissions sont vérifiées au niveau de l'agent associé à la conversation.

Endpoints disponibles

GET /v1/conversations/:id/metrics - Métriques d'une conversation

Récupère les métriques détaillées d'un message spécifique, incluant les statistiques de tokens et les appels de conversation associés.

Paramètres

Paramètre	Type	Requis	Description
`id`	String (CUID)	Oui	ID du message de conversation

Requête

http

GET /v1/conversations/cm4msg123abc/metrics
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

json

{
  "success": true,
  "data": {
    "id": "cm4msg123abc",
    "message": "Voici les résultats de votre analyse...",
    "score": 0.95,
    "type": "assistant",
    "model": "gpt-4",
    "sources":

Champs de la réponse

Champ	Type	Description
`id`	String	Identifiant unique du message
`message`	String	Contenu du message
`score`	Number	Score de pertinence (0-1)
`type`	String	Rôle : `user`, `assistant`, `system`
`model`	String	Modèle utilisé (ou modèle custom si défini)

Exemple avec curl

bash

curl -X GET https://api.devana.ai/v1/conversations/cm4msg123abc/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/conversations/:id/messages - Messages d'une conversation

Récupère tous les messages d'une conversation, incluant le message principal et toutes les réponses.

Paramètres

Paramètre	Type	Requis	Description
`id`	String (CUID)	Oui	ID de la conversation

Query Parameters

Paramètre	Type	Requis	Description
`flagged`	Boolean	Non	Si `true`, retourne uniquement les messages marqués par la modération

Requête

http

GET /v1/conversations/cm4conv789xyz/messages
Authorization: Bearer YOUR_API_KEY

Requête avec filtre de modération

http

GET /v1/conversations/cm4conv789xyz/messages?flagged=true
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

json

{
  "success": true,
  "data": [
    {
      "id": "cm4msg001",
      "date": "2024-10-28T10:00:00.000Z",
      "message": "Comment optimiser cette fonction Python ?",
      "role": "user",
      "model": null,
      "score"

Structure des messages

Champ	Type	Description
`id`	String	Identifiant unique du message
`date`	DateTime	Date et heure du message
`message`	String	Contenu du message
`role`	String	`user`, `assistant`, ou `system`
`model`	String	Modèle utilisé (null pour user)

Exemple avec curl

bash

# Tous les messages
curl -X GET https://api.devana.ai/v1/conversations/cm4conv789xyz/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

# Messages marqués uniquement
curl -X GET "https://api.devana.ai/v1/conversations/cm4conv789xyz/messages?flagged=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE /v1/conversations/:id - Supprimer une conversation

Supprime une conversation et tous ses messages enfants de manière récursive (soft delete).

Paramètres

Paramètre	Type	Requis	Description
`id`	String (CUID)	Oui	ID de la conversation à supprimer

Requête

http

DELETE /v1/conversations/cm4conv789xyz
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

json

{
  "success": true,
  "data": {
    "message": "Conversation deleted successfully",
    "deletedId": "cm4conv789xyz"
  }
}

Comportement de suppression

Soft delete : Les conversations ne sont pas physiquement supprimées mais marquées avec deletedAt
Récursive : Tous les messages enfants sont également marqués comme supprimés
Cascade : La hiérarchie complète est traitée automatiquement
Réversible : Possibilité de restauration côté base de données si nécessaire

Exemple avec curl

bash

curl -X DELETE https://api.devana.ai/v1/conversations/cm4conv789xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

Modèles de données

Message de conversation

typescript

interface ConversationMessage {
  id: string; // CUID unique
  date: DateTime; // Date de création
  message: string; // Contenu du message
  role: "user" | "assistant" | "system";
  model: string | null; // Modèle utilisé
  score: number | null; // Score de qualité (0-1)
  sources: Source[] | null; // Sources référencées
  tokens: number | null; // Nombre de tokens du message
  contextTokens: number | null; // Tokens de contexte
  toolCalls:  | ; 
}

Métriques de conversation

typescript

interface ConversationMetrics {
  id: string;
  message: string;
  score: number | null;
  type: "user" | "assistant" | "system";
  model: string; // Nom du modèle custom ou standard
  sources: Source[] | null;
  status: string | null;
  agent: string; // ID de l'agent
  tokens: {
    message: number | null;
    context: number | null;
  };
  conversationCalls: ConversationCall[];
}

Appel de conversation

typescript

interface ConversationCall {
  type: string; // Type d'appel (completion, embedding, etc.)
  messages: object | null; // Messages envoyés
  messagesTokens: number | null; // Tokens des messages
  outputContent: string | null; // Contenu généré
  outputTokens: number | null; // Tokens générés
  timeMs: number | null; // Temps d'exécution en ms
}

Source

typescript

interface Source {
  fileName: string; // Nom du fichier source
  page?: number; // Page (si applicable)
  relevance: number; // Score de pertinence (0-1)
  excerpt?: string; // Extrait pertinent
}

Fonctionnalités spéciales

Suppression récursive

La suppression d'une conversation parent entraîne automatiquement :

Identification de tous les messages enfants
Suppression récursive des enfants
Marquage avec deletedAt (soft delete)
Conservation de l'intégrité référentielle

Contrôle d'accès

Chaque endpoint vérifie :

Authentification via API Key
Existence de la conversation
Droits sur l'agent associé via guardAuthorizedAgentRights
Non-suppression préalable (deletedAt: null)

Support des modèles personnalisés

Les endpoints retournent automatiquement :

Le nom du modèle personnalisé si configuré
Le modèle standard en fallback
Les métriques spécifiques au modèle utilisé

Modération des contenus

Le paramètre flagged permet de :

Filtrer les messages problématiques
Identifier les contenus nécessitant une revue
Implémenter des workflows de modération

Exemples d'intégration

Dashboard de métriques

javascript

Système de modération

python

Export et archivage

bash

#!/bin/bash

# Script d'export et archivage de conversations

API_KEY="YOUR_API_KEY"
BASE_URL="https://api.devana.ai/v1"
EXPORT_DIR="./conversation_exports"

# Créer le répertoire d'export
mkdir -p $EXPORT_DIR

export_conversation() {
  local conv_id=$1
  local export_file="$EXPORT_DIR/conversation_${conv_id}_$(date +%Y%m%d_%H%M%S).json"

   

  
  curl -s -X GET  \
    -H  > 

  
   [ $? -eq 0 ]; 
    
    jq   > 
     

    
    messages=$(jq -r  )

     msg_id  ; 
       

      curl -s -X GET  \
        -H  > 
    

     
  
     
     
  
}


export_conversation 


CONVERSATION_IDS=(  )

 conv_id  ; 
  export_conversation 



 
tar -czf

Différences avec l'API publique

API Conversations (`/v1/conversations`)

Usage : Gestion CRUD des conversations existantes
Authentification : API Key requise
Permissions : Basées sur l'agent
Fonctions : Métriques, historique, suppression

API Public Conversations (`/v1/chat/conversation`)

Usage : Conversations embedables et widgets
Authentification : Tokens de sécurité ou OAuth
Permissions : Publiques avec tokens
Fonctions : Streaming, chat en temps réel

Pour les conversations publiques et widgets, consultez Public Conversations API.

Codes d'erreur

Code	Message	Description	Solution
`400`	Bad Request	Paramètres invalides (ID non CUID)	Vérifier le format de l'ID
`403`	Forbidden	Pas d'autorisation sur l'agent	Vérifier les permissions
`404`	Not Found	Conversation/Message introuvable	Vérifier l'ID et la suppression
`500`	Internal Server Error	Erreur serveur	Réessayer ou contacter le support

Limites et quotas

Limite	Valeur	Description
Messages par requête	1000	Maximum retourné par `/messages`
Profondeur récursive	Illimitée	Pour la suppression cascade
Rétention soft delete	30 jours	Avant suppression définitive
Rate limit	100 req/min	Par API Key

Support et assistance

Pour toute question ou problème concernant l'API Conversations :

Consultez la documentation générale de l'API
Pour créer des conversations : Chat Completions API
Pour les conversations publiques : Public Conversations API
Contactez le support technique : support@devana.ai
Reportez les bugs sur notre GitHub

SDK

Notes de version

Conformité

Conversations API

📑 Table des matières

Vue d'ensemble

Authentification

Endpoints disponibles

GET /v1/conversations/:id/metrics - Métriques d'une conversation

Paramètres

Requête

Réponse (200 OK)

Champs de la réponse

Exemple avec curl

GET /v1/conversations/:id/messages - Messages d'une conversation

Paramètres

Query Parameters

Requête

Requête avec filtre de modération

Réponse (200 OK)

Structure des messages

Exemple avec curl

DELETE /v1/conversations/:id - Supprimer une conversation

Paramètres

Requête

Réponse (200 OK)

Comportement de suppression

Exemple avec curl

Modèles de données

Message de conversation

Métriques de conversation

Appel de conversation

Source

Fonctionnalités spéciales

Suppression récursive

Contrôle d'accès

Support des modèles personnalisés

Modération des contenus

Exemples d'intégration

Dashboard de métriques

Système de modération

Export et archivage

Différences avec l'API publique

API Conversations (/v1/conversations)

API Public Conversations (/v1/chat/conversation)

Codes d'erreur

Limites et quotas

Support et assistance

API Conversations (`/v1/conversations`)

API Public Conversations (`/v1/chat/conversation`)