API-overblik

Diaforms API giver din egen kode og dine AI-agenter adgang til den feedback, du indsamler: projekter, samtaler med AI-opsummeringer og hele transskriptioner samt AI-rapporter. Brug det til at analysere svar med din egen agent, sende data til et data warehouse eller starte automatiseringer.

Du kan oprette forbindelse på to måder, og begge bruger den samme API-nøgle og returnerer de samme data:

• REST API. JSON over HTTPS til scripts, backends og automatiseringsværktøjer.
• MCP-server. Til AI-agenter som Claude Code, Codex eller Cursor. Agenten får API'et som værktøjer, den kan kalde direkte. Se MCP-server.

Det kan du gøre#

Vil du have besked, når en samtale slutter, i stedet for at spørge API'et igen og igen, så brug webhooks.

Før du starter#

Du skal bruge to ting:

1. En Pro-, Business- eller Enterprise-plan.
2. En API-nøgle. Ejere og admins opretter nøgler under Indstillinger → Generelt → API-nøgler.

For at oprette en nøgle klikker du på Ny API-nøgle, giver den et navn og klikker på Opret nøgle. Klik på Kopiér i dialogen Din nye API-nøgle og derefter på Jeg har gemt min nøgle. Diaform viser kun nøglen én gang.

Nøgler ser ud som dia_org_live_ efterfulgt af 32 tegn. De udløber ikke. Hver organisation kan have op til 10. For at slå en fra klikker du på Tilbagekald og derefter på Tilbagekald API-nøgle. Alt, der bruger nøglen, holder op med at virke med det samme.

Godkendelse#

Send nøglen som bearer-token i hver forespørgsel:

Authorization: Bearer dia_org_live_...

En nøgle kan læse alle projekter i sin organisation, uanset projektets adgangsindstillinger. Hold den på din server eller i din agents konfiguration, og læg den aldrig i kode til browseren eller en app. Eksemplerne i denne dokumentation læser den fra miljøvariablen DIAFORM_API_KEY.

Basis-URL og konventioner#

https://diaform.io/api/v1

• Forespørgsler og svar er JSON. Feltnavne bruger snake_case.
• ID'er er UUID'er. Tidsstempler er ISO 8601-strenge i UTC.
• Et felt uden værdi er null. Det udelades aldrig.
• API'et kalder en interviewer et projekt, ligesom dashboardet. Et projekt-ID er ID'et efter /agents/ i projektets URL i dashboardet og efter /c/ i dets offentlige link.
• Samtaler, der er startet fra Forhåndsvis i dashboardet, returneres aldrig.

Send din første forespørgsel#

Hent en liste over dine projekter:

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

Hent derefter de gennemførte samtaler i et af dem:

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#

Endpoints, der returnerer lister, giver de nyeste elementer først i dette format:

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

For at hente den næste side gentager du forespørgslen med de samme filtre og cursor sat til next_cursor. På den sidste side er has_more lig med false, og next_cursor er 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;
}

Fejl#

Fejl bruger almindelige HTTP-statuskoder og returnerer JSON med en læsbar besked i error og en stabil code, som din kode kan reagere på:

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

En 400 har også details med én post pr. ugyldigt felt:

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

Et ID fra en anden organisation returnerer 404, ligesom et ID, der ikke findes.

Grænser for forespørgsler#

Hver API-nøgle kan sende 120 forespørgsler i minuttet til læse-endpoints og MCP-serveren tilsammen. Over den grænse returnerer forespørgsler 429 med headeren Retry-After: 60. Hver side returnerer op til 100 elementer.

Giv din agent denne dokumentation#

Hver side i dokumentationen har knappen Kopiér side, som kopierer siden som Markdown, klar til at indsætte i en AI-agent. Hver side findes også som ren Markdown, og hele API-referencen findes som én fil:

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

Giv din agent den URL, eller forbind den direkte med MCP-serveren.