Vue d’ensemble de l’API

L’API Diaform donne à votre propre code et à vos agents IA l’accès au feedback que vous recueillez : les projets, les conversations avec leurs résumés IA et leurs transcriptions complètes, et les rapports IA. Utilisez-la pour analyser les réponses avec votre propre agent, alimenter un entrepôt de données ou déclencher des automatisations.

Il y a deux façons de se connecter. Les deux utilisent la même clé API et renvoient les mêmes données :

• API REST. Du JSON sur HTTPS, pour les scripts, les backends et les outils d’automatisation.
• Serveur MCP. Pour les agents IA comme Claude Code, Codex ou Cursor. L’agent reçoit l’API sous forme d’outils qu’il peut appeler directement. Consultez Serveur MCP.

Ce que vous pouvez faire#

Pour être prévenu quand une conversation se termine, sans interroger l’API à intervalles réguliers, utilisez les webhooks.

Avant de commencer#

Il vous faut deux choses :

1. Une offre Pro, Business ou Enterprise.
2. Une clé API. Les propriétaires et les admins créent des clés dans Paramètres → Général → Clés API.

Pour créer une clé, cliquez sur Nouvelle clé API, donnez-lui un nom, puis cliquez sur Créer la clé. Dans la fenêtre Votre nouvelle clé API, cliquez sur Copier, puis sur J’ai enregistré ma clé. Diaform n’affiche la clé qu’une seule fois.

Les clés ressemblent à dia_org_live_ suivi de 32 caractères. Elles n’expirent pas. Chaque organisation peut en avoir jusqu’à 10. Pour en désactiver une, cliquez sur Révoquer, puis sur Révoquer la clé API. Tout ce qui utilise cette clé cesse immédiatement de fonctionner.

Authentification#

Envoyez la clé comme jeton bearer dans chaque requête :

Authorization: Bearer dia_org_live_...

Une clé peut lire tous les projets de son organisation, quels que soient les paramètres d’accès du projet. Gardez-la sur votre serveur ou dans la configuration de votre agent, et ne la placez jamais dans du code de navigateur ou d’application. Les exemples de cette documentation la lisent depuis une variable d’environnement DIAFORM_API_KEY.

URL de base et conventions#

https://diaform.io/api/v1

• Les requêtes et les réponses sont en JSON. Les noms de champs sont en snake_case.
• Les ID sont des UUID. Les horodatages sont des chaînes ISO 8601 en UTC.
• Un champ sans valeur vaut null. Il n’est jamais omis.
• L’API appelle un intervieweur un projet, comme le tableau de bord. L’ID d’un projet est l’ID qui suit /agents/ dans l’URL du projet dans le tableau de bord, et /c/ dans son lien public.
• Les conversations lancées depuis l’Aperçu du tableau de bord ne sont jamais renvoyées.

Envoyer votre première requête#

Listez vos projets :

curl "https://diaform.io/api/v1/projects" \
  -H "Authorization: Bearer $DIAFORM_API_KEY"

Récupérez ensuite les conversations terminées de l’un d’eux :

curl -G "https://diaform.io/api/v1/projects/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d/conversations" \
  -H "Authorization: Bearer $DIAFORM_API_KEY" \
  --data-urlencode "status=completed" \
  --data-urlencode "limit=50"

Pagination#

Les endpoints de liste renvoient les éléments les plus récents en premier, sous cette forme :

{
  "data": [],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTA1LTA3VDEyOjAwOjAwLjEyMzQ1NiswMDowMCIsIjBmOGQ0M2EyIl0"
}

Pour obtenir la page suivante, répétez la requête avec les mêmes filtres et donnez à cursor la valeur de next_cursor. Sur la dernière page, has_more vaut false et next_cursor vaut null.

async function listAllConversations(projectId) {
  const conversations = [];
  let cursor = null;

  do {
    const url = new URL(
      `https://diaform.io/api/v1/projects/${projectId}/conversations`,
    );
    url.searchParams.set("status", "completed");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.DIAFORM_API_KEY}` },
    });
    if (!response.ok) throw new Error((await response.json()).error);

    const page = await response.json();
    conversations.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);

  return conversations;
}

Erreurs#

Les erreurs utilisent les codes de statut HTTP standard et renvoient du JSON avec un message error lisible et un code stable, que votre code peut tester :

{
  "error": "No project with this ID exists in your organization.",
  "code": "not_found"
}

Une erreur 400 contient aussi details, avec une entrée par champ invalide :

{
  "error": "The request has invalid parameters.",
  "code": "invalid_request",
  "details": [
    { "field": "limit", "message": "Too big: expected number to be <=100" }
  ]
}

Un ID d’une autre organisation renvoie 404, comme un ID qui n’existe pas.

Limites de débit#

Chaque clé API peut envoyer 120 requêtes par minute, endpoints de lecture et serveur MCP confondus. Au-delà, les requêtes renvoient 429 avec un en-tête Retry-After: 60. Chaque page renvoie jusqu’à 100 éléments.

Donner cette documentation à votre agent#

Chaque page de la documentation a un bouton Copier la page qui la copie en Markdown, prête à coller dans un agent IA. Chaque page est aussi disponible en Markdown brut, et toute la référence de l’API tient dans un seul fichier :

https://diaform.io/api/docs-markdown/api

Indiquez cette URL à votre agent, ou connectez-le directement avec le serveur MCP.