Documentaliste

Ce document décrit comment utiliser l’API DIMARC pour interagir avec l’endpoint /documentalist. Cet endpoint permet d’envoyer des requêtes à un agent documentaliste avec une question, des instructions spécifiques et un historique de conversation.

POST /v2/documentalist

Prérequis

Un compte DIMARC actif.
Être administrateur de votre organisation.
Un agent de type “Documentaliste” configurer.
Votre agent doit avoir une visibilité configurée sur Public ou Organisation pour être utilisable via l’API.
Votre token d’authentification x-api-key (voir Récupération de votre Token d’Authentification)

Récupérer l’ID d’un agent

Chacun des agents à un id unique. Pour récupérer l’ID de l’agent Documentaliste, rendez-vous sur votre tableau de bord

Cliquez en haut à droite sur l’icône de votre profil puis accédez à la section Organisation > API ou en cliquant ici
Dans la section Références de vos agents, vous pouvez récupérer l’ID de l’agent Documentaliste que vous souhaitez utiliser.

Communiquez avec votre Documentaliste

Pour communiquer avec l’agent Documentaliste, envoyez une requête POST à l’endpoint /v2/documentalist/<agent_id> avec votre token d’authentification.

Paramètres de requête

Paramètre	Type	Description
`query`	string	La question ou requête à adresser à l’agent documentaliste
`instructions`	array	Liste d’instructions spécifiques pour guider la réponse de l’agent (optionnel)
`historic`	array	Historique des conversations précédentes (optionnel)
`thread_id`	string	UUID de 36 caractères pour maintenir un historique de conversation persistant (optionnel)

Exemple de requête

curl --location 'https://api.dimarc.ai/v2/documentalist/<agent_id>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "query": "Que fait Dimarc ?",
    "instructions": ["Ajoute des 🌈 dans tes réponses"],
    "historic": []
}'

Format de réponse

La réponse est un flux texte brut (ReadableStream), toujours en HTTP 200.

En cas de succès, le flux contient directement la réponse de l’agent :

Dimarc est une plateforme d'intelligence artificielle spécialisée dans la création d'agents IA personnalisés.

En cas d’échec interne (file de traitement indisponible, timeout, agent qui n’a pas pu répondre), le même texte d’excuse est renvoyé, toujours en HTTP 200 — impossible de distinguer une erreur réelle d’une réponse normale sans inspecter le contenu :

Désolé, je ne peux pas vous donner de réponse pour le moment.

Seuls deux cas court-circuitent le flux avec un vrai status HTTP d’erreur, sous forme de texte brut (hors enveloppe JSON) :

Status	Cas
404	Agent introuvable, mauvais type, privé, ou hors de votre organisation
404	`thread_id` fourni ne correspond pas à un thread de cet agent

Gestion de l’historique de conversation

Pour maintenir un contexte cohérent au fil des échanges, vous disposez de deux options :

Option 1 : Utiliser le paramètre `thread_id`

Vous pouvez passer un thread_id (UUID de 36 caractères) pour maintenir automatiquement un historique de conversation persistant côté serveur. Cela permet de conserver le contexte entre plusieurs appels API sans avoir à gérer manuellement l’historique.

Option 2 : Fournir l’historique manuellement

Vous pouvez inclure l’historique des conversations précédentes dans le paramètre historic. Cela permet à l’agent de comprendre le contexte complet de l’échange.

Format de l’historique

L’historique doit être fourni sous forme d’un tableau d’objets alternant entre les messages de l’utilisateur et les réponses de l’agent :

"historic": [
  {
    "role": "user",
    "content": "Que fait Dimarc ?"
  },
  {
    "role": "assistant",
    "content": "🌈 Dimarc est une plateforme d'intelligence artificielle spécialisée dans la création d'agents IA personnalisés. 🌈"
  }
]

Limites et considérations

Les temps de réponse peuvent varier selon la complexité de la requête et les sources d’informations que l’agent Documentaliste décidé d’utiliser.
Les sources utilisées par l’agent Documentaliste ne sont pas retourner dans la réponse pour le moment.

Support et assistance

Pour toute question concernant l’API Documentalist, contactez notre équipe de support à l’adresse contact@dimarc.fr