API-overzicht

Met de Diaform API hebben je eigen code en je AI-agents toegang tot de feedback die je verzamelt: projecten, gesprekken met hun AI-samenvattingen en volledige transcripten, en AI-rapporten. Gebruik de API om antwoorden te analyseren met je eigen agent, een datawarehouse te vullen of automatiseringen te starten.

Je kunt op twee manieren verbinding maken. Beide gebruiken dezelfde API-sleutel en geven dezelfde data terug:

• REST API. JSON via HTTPS, voor scripts, backends en automatiseringstools.
• MCP-server. Voor AI-agents zoals Claude Code, Codex of Cursor. De agent krijgt de API als tools die hij direct kan aanroepen. Zie MCP-server.

Wat je kunt doen#

Wil je een melding krijgen wanneer een gesprek eindigt, in plaats van te pollen? Gebruik dan webhooks.

Voordat je begint#

Je hebt twee dingen nodig:

1. Een Pro-, Business- of Enterprise-abonnement.
2. Een API-sleutel. Eigenaren en beheerders maken sleutels aan onder Instellingen → Algemeen → API-sleutels.

Om een sleutel te maken, klik je op Nieuwe API-sleutel, geef je hem een naam en klik je op Sleutel maken. Klik in het venster Je nieuwe API-sleutel op Kopiëren en daarna op Ik heb mijn sleutel bewaard. Diaform toont de sleutel maar één keer.

Sleutels zien eruit als dia_org_live_ gevolgd door 32 tekens. Ze verlopen niet. Elke organisatie kan er maximaal 10 hebben. Om er een uit te zetten, klik je op Intrekken en daarna op API-sleutel intrekken. Alles wat de sleutel gebruikt, werkt dan meteen niet meer.

Authenticatie#

Stuur de sleutel bij elk request mee als bearer-token:

Authorization: Bearer dia_org_live_...

Een sleutel kan elk project in zijn organisatie lezen, ongeacht de toegangsinstellingen van het project. Bewaar hem op je server of in de configuratie van je agent, en zet hem nooit in browser- of app-code. De voorbeelden in deze documentatie lezen hem uit een omgevingsvariabele DIAFORM_API_KEY.

Basis-URL en conventies#

https://diaform.io/api/v1

• Requests en responses zijn JSON. Veldnamen staan in snake_case.
• ID's zijn UUID's. Tijdstempels zijn ISO 8601-strings in UTC.
• Een veld zonder waarde is null. Het wordt nooit weggelaten.
• De API noemt een interviewer een project, net als het dashboard. Een project-ID is de ID na /agents/ in de dashboard-URL van het project, en na /c/ in de openbare link.
• Gesprekken die zijn gestart vanuit Voorbeeld in het dashboard, worden nooit teruggegeven.

Je eerste request#

Haal je projecten op:

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

Haal daarna de afgeronde gesprekken van een van die projecten op:

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"

Paginering#

Lijst-endpoints geven de nieuwste items eerst terug, in deze vorm:

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

Voor de volgende pagina herhaal je het request met dezelfde filters en zet je cursor op next_cursor. Op de laatste pagina is has_more false en next_cursor 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;
}

Fouten#

Fouten gebruiken de standaard HTTP-statuscodes en geven JSON terug met een leesbare error-melding en een stabiele code waarop je code kan reageren:

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

Een 400 heeft ook details, met één item per ongeldig veld:

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

Een ID uit een andere organisatie geeft 404, net als een ID die niet bestaat.

Ratelimits#

Elke API-sleutel kan 120 requests per minuut doen naar de lees-endpoints en de MCP-server samen. Daarboven geven requests 429 terug met de header Retry-After: 60. Elke pagina bevat maximaal 100 items.

Geef deze documentatie aan je agent#

Elke pagina van de documentatie heeft een knop Pagina kopiëren die de pagina als Markdown kopieert, klaar om in een AI-agent te plakken. Elke pagina is ook beschikbaar als platte Markdown, en de hele API-referentie als één bestand:

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

Geef je agent die URL, of verbind hem direct via de MCP-server.