API-Überblick

Die Diaform-API gibt deinem eigenen Code und deinen KI-Agenten Zugriff auf das Feedback, das du sammelst: Projekte, Gespräche mit ihren KI-Zusammenfassungen und vollständigen Transkripten sowie KI-Berichte. Nutze sie, um Antworten mit deinem eigenen Agenten auszuwerten, ein Data Warehouse zu befüllen oder Automatisierungen auszulösen.

Es gibt zwei Wege, dich zu verbinden. Beide nutzen denselben API-Schlüssel und liefern dieselben Daten:

• REST-API. JSON über HTTPS, für Skripte, Backends und Automatisierungstools.
• MCP-Server. Für KI-Agenten wie Claude Code, Codex oder Cursor. Der Agent bekommt die API als Tools, die er direkt aufrufen kann. Siehe MCP-Server.

Was du tun kannst#

Wenn du benachrichtigt werden willst, sobald ein Gespräch endet, statt die API regelmäßig abzufragen, nutze Webhooks.

Bevor du loslegst#

Du brauchst zwei Dinge:

1. Einen Pro-, Business- oder Enterprise-Tarif.
2. Einen API-Schlüssel. Inhaber und Admins erstellen Schlüssel unter Einstellungen → Allgemein → API-Schlüssel.

Um einen Schlüssel zu erstellen, klick auf Neuer API-Schlüssel, gib ihm einen Namen und klick auf Schlüssel erstellen. Klick im Dialog Dein neuer API-Schlüssel auf Kopieren und dann auf Ich habe meinen Schlüssel gespeichert. Diaform zeigt den Schlüssel nur einmal an.

Schlüssel sehen so aus: dia_org_live_ gefolgt von 32 Zeichen. Sie laufen nicht ab. Jede Organisation kann bis zu 10 haben. Um einen abzuschalten, klick auf Widerrufen und dann auf API-Schlüssel widerrufen. Alles, was den Schlüssel nutzt, funktioniert sofort nicht mehr.

Authentifizierung#

Sende den Schlüssel bei jeder Anfrage als Bearer-Token:

Authorization: Bearer dia_org_live_...

Ein Schlüssel kann jedes Projekt seiner Organisation lesen, unabhängig von den Zugriffseinstellungen des Projekts. Bewahr ihn auf deinem Server oder in der Konfiguration deines Agenten auf und pack ihn nie in Browser- oder App-Code. Die Beispiele in dieser Doku lesen ihn aus der Umgebungsvariable DIAFORM_API_KEY.

Basis-URL und Konventionen#

https://diaform.io/api/v1

• Anfragen und Antworten sind JSON. Feldnamen stehen in snake_case.
• IDs sind UUIDs. Zeitstempel sind ISO-8601-Strings in UTC.
• Ein Feld ohne Wert ist null. Es wird nie weggelassen.
• Die API nennt einen Interviewer Projekt, wie das Dashboard. Eine Projekt-ID ist die ID nach /agents/ in der Dashboard-URL des Projekts und nach /c/ in seinem öffentlichen Link.
• Gespräche, die über die Vorschau im Dashboard gestartet wurden, werden nie zurückgegeben.

Deine erste Anfrage#

Liste deine Projekte auf:

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

Ruf dann die abgeschlossenen Gespräche eines dieser Projekte ab:

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"

Paginierung#

Listen-Endpunkte geben die neuesten Einträge zuerst zurück, in dieser Form:

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

Um die nächste Seite abzurufen, wiederhole die Anfrage mit denselben Filtern und setz cursor auf next_cursor. Auf der letzten Seite ist has_more false und 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;
}

Fehler#

Fehler nutzen die üblichen HTTP-Statuscodes und liefern JSON mit einer lesbaren error-Meldung und einem stabilen code, den dein Code auswerten kann:

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

Ein 400 enthält zusätzlich details, mit einem Eintrag pro ungültigem Feld:

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

Eine ID aus einer anderen Organisation liefert 404, genau wie eine, die es nicht gibt.

Ratenlimits#

Jeder API-Schlüssel kann pro Minute 120 Anfragen an die Lese-Endpunkte und den MCP-Server zusammen stellen. Darüber hinaus liefern Anfragen 429 mit dem Header Retry-After: 60. Jede Seite enthält bis zu 100 Einträge.

Gib diese Doku deinem Agenten#

Jede Seite der Doku hat den Button Seite kopieren. Er kopiert sie als Markdown, fertig zum Einfügen in einen KI-Agenten. Jede Seite gibt es auch als reines Markdown und die gesamte API-Referenz als eine Datei:

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

Gib deinem Agenten diese URL oder verbinde ihn direkt über den MCP-Server.