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
  • GET /v1/conversations/:id/metrics
  • GET /v1/conversations/:id/messages
  • DELETE /v1/conversations/:id
• 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 :

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

Requête

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

Réponse (200 OK)

{
  "success": true,
  "data": {
    "id": "cm4msg123abc",
    "message": "Voici les résultats de votre analyse...",
    "score": 0.95,
    "type": "assistant",
    "model": "gpt-4",
    "sources": [
      {
        "fileName": "guide.pdf",
        "page": 12,
        "relevance": 0.89
      }
    ],
    "status": "completed",
    "agent": "cm4agent456def",
     
       
       
    
     
      
         
         
           
           
        
         
         
         
         
      
      
         
         
         
         
         
         
      
    
  

Champs de la réponse

Exemple avec curl

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

Query Parameters

Requête

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

Requête avec filtre de modération

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

Réponse (200 OK)

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

Structure des messages

Exemple avec curl

# 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

Requête

DELETE /v1/conversations/cm4conv789xyz
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

{
  "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

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

Modèles de données

Message de conversation

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: object | null; // Appels d'outils effectués
}

Métriques de conversation

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

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

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 :

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

Contrôle d'accès

Chaque endpoint vérifie :

1. Authentification via API Key
2. Existence de la conversation
3. Droits sur l'agent associé via guardAuthorizedAgentRights
4. 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

class ConversationMetrics {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://api.devana.ai/v1";
  }

  async getConversationStats(conversationId) {
    // Récupérer tous les messages
    const messagesResponse = await fetch(
      `${this.baseUrl}/conversations/${conversationId}/messages`,
      {
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
        },
      }
    );

    const messages = await messagesResponse.json();

    // Calculer les statistiques
    const stats = {
      totalMessages: messages.data.length,
      userMessages: messages.data.filter((m) => m.role === "user").length,
      assistantMessages: messages.data.filter((m) => m.role === )
        .,
      : ,
      : ,
      :  (),
    };

    
     ( message  messages.) {
       (message.) {
        stats. += message.;
      }

       (message.) {
        stats. += message.;
      }

       (message.) {
        message..( {
          stats..(source.);
        });
      }
    }

    stats. = stats. / stats. || ;
    stats. = stats..;

    
     lastAssistant = messages.
      .( m. === )
      .();

     (lastAssistant) {
       metricsResponse =  (
        ,
        {
          : {
            : ,
          },
        }
      );

       metrics =  metricsResponse.();
      stats. = metrics...(
         sum + (call. || ),
        
      );
    }

     stats;
  }

   () {
     report = {
      : [],
      : ,
      : ,
    };

     ( id  conversationIds) {
       response =  (
        ,
        {
          : {
            : ,
          },
        }
      );

       messages =  response.();

       conversationTokens = messages..( {
         sum + (msg. || ) + (msg. || );
      }, );

      report..({
        id,
        : conversationTokens,
        : messages..,
      });

      report. += conversationTokens;
    }

    
    report. = (report. / ) * ; 

     report;
  }
}


 metrics =  ();


 stats =  metrics.();
.(, stats);


 report =  metrics.([
  ,
  ,
  ,
]);
.(, report);

Système de modération

import requests
from typing import List, Dict
from datetime import datetime

class ConversationModerator:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.devana.ai/v1"
        self.headers = {"Authorization": f"Bearer {api_key}"}

    def get_flagged_messages(self, conversation_id: str) -> List[Dict]:
        """Récupère tous les messages marqués par la modération"""

        response = requests.get(
            f"{self.base_url}/conversations/{conversation_id}/messages",
            headers=self.headers,
            params={"flagged": "true"}
        )

        if response.status_code == 200:
            return response.json()["data"]
        return []

    def analyze_conversation_safety(self, conversation_id: str) -> Dict:
        """Analyse la sécurité d'une conversation"""

        # Récupérer tous les messages
        all_messages = .get_all_messages(conversation_id)
        flagged_messages = .get_flagged_messages(conversation_id)

        analysis = {
            : conversation_id,
            : (all_messages),
            : (flagged_messages),
            :  - ((flagged_messages) / (all_messages))  all_messages  ,
            : (flagged_messages) > ,
            : []
        }

        
         msg  flagged_messages:
            analysis[].append({
                : msg[],
                : msg[],
                : msg[][:] +   (msg[]) >   msg[],
                : msg[]
            })

         analysis

     () -> []:
        

        response = requests.get(
            ,
            headers=.headers
        )

         response.status_code == :
             response.json()[]
         []

     () -> :
        

        analysis = .analyze_conversation_safety(conversation_id)

         analysis[] < threshold:
            response = requests.delete(
                ,
                headers=.headers
            )

             response.status_code == :
                ()
                 

         

     () -> :
        

        report = {
            : datetime.now().isoformat(),
            : (conversation_ids),
            : ,
            : ,
            : []
        }

         conv_id  conversation_ids:
            analysis = .analyze_conversation_safety(conv_id)

             analysis[]:
                report[] += 
                report[] += analysis[]

            report[].append(analysis)

        
        report[].sort(key= x: x[])

         report


moderator = ConversationModerator()


analysis = moderator.analyze_conversation_safety()
()


report = moderator.generate_moderation_report([
    ,
    ,
    
])

()

Export et archivage

#!/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"

  echo "Exporting conversation $conv_id..."

  # Récupérer les messages
  curl -s -X GET "$BASE_URL/conversations/$conv_id/messages" \
    -H "Authorization: Bearer $API_KEY" > "$export_file.tmp"

  # Vérifier le succès
  if [ $? -eq 0 ]; then
    # Formatter le JSON
    jq '.' "$export_file.tmp" > "$export_file"
    rm "$export_file.tmp"

    # Récupérer les métriques pour chaque message
    messages=$(jq -r '.data[].id' "$export_file")

    for msg_id in $messages; 
       

      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

Limites et quotas

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