API-oversikt

Diaform-API-et gir din egen kode og AI-agentene dine tilgang til tilbakemeldingene du samler inn: prosjekter, samtaler med AI-sammendrag og hele transkripsjoner, og AI-rapporter. Bruk det til å analysere svar med din egen agent, sende data til et datavarehus eller starte automatiseringer.

Du kan koble til på to måter, og begge bruker den samme API-nøkkelen og returnerer de samme dataene:

• REST API. JSON over HTTPS, for skript, backender og automatiseringsverktøy.
• MCP-server. For AI-agenter som Claude Code, Codex eller Cursor. Agenten får API-et som verktøy den kan kalle direkte. Se MCP-server.

Dette kan du gjøre#

Vil du få beskjed når en samtale avsluttes, i stedet for å spørre API-et om og om igjen, bruker du webhooks.

Før du starter#

Du trenger to ting:

1. Planen Pro, Business eller Enterprise.
2. En API-nøkkel. Eiere og administratorer lager nøkler under Innstillinger → Generelt → API-nøkler.

For å lage en nøkkel klikker du på Ny API-nøkkel, gir den et navn og klikker på Opprett nøkkel. I dialogen Den nye API-nøkkelen din klikker du på Kopier og deretter på Jeg har lagret nøkkelen. Diaform viser nøkkelen bare én gang.

Nøkler ser ut som dia_org_live_ etterfulgt av 32 tegn. De utløper ikke. Hver organisasjon kan ha opptil 10. For å slå av en nøkkel klikker du på Tilbakekall og deretter på Tilbakekall API-nøkkel. Alt som bruker nøkkelen, slutter å virke med en gang.

Autentisering#

Send nøkkelen som et bearer-token i hver forespørsel:

Authorization: Bearer dia_org_live_...

En nøkkel kan lese alle prosjekter i organisasjonen sin, uansett hvilke tilgangsinnstillinger prosjektet har. Hold den på serveren din eller i konfigurasjonen til agenten din, og legg den aldri i kode i nettleseren eller appen. Eksemplene i denne dokumentasjonen leser den fra miljøvariabelen DIAFORM_API_KEY.

Basis-URL og konvensjoner#

https://diaform.io/api/v1

• Forespørsler og svar er JSON. Feltnavn bruker snake_case.
• ID-er er UUID-er. Tidsstempler er ISO 8601-strenger i UTC.
• Et felt uten verdi er null. Det utelates aldri.
• API-et kaller en intervjuer et prosjekt, slik dashbordet gjør. En prosjekt-ID er ID-en etter /agents/ i URL-en til prosjektet i dashbordet, og etter /c/ i den offentlige lenken.
• Samtaler som er startet fra Forhåndsvis i dashbordet, returneres aldri.

Send din første forespørsel#

List opp prosjektene dine:

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

Hent deretter de fullførte samtalene i ett av 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#

Endepunkter som returnerer lister, gir de nyeste elementene først, i dette formatet:

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

For å hente neste side gjentar du forespørselen med de samme filtrene og cursor satt til next_cursor. På den siste siden er has_more lik 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;
}

Feil#

Feil bruker vanlige HTTP-statuskoder og returnerer JSON med en lesbar error-melding og en stabil code som koden din kan reagere på:

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

En 400 har også details, med én oppføring per ugyldig felt:

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

En ID fra en annen organisasjon returnerer 404, akkurat som en ID som ikke finnes.

Grenser for forespørsler#

Hver API-nøkkel kan sende 120 forespørsler i minuttet til leseendepunktene og MCP-serveren til sammen. Over den grensen returnerer forespørsler 429 med headeren Retry-After: 60. Hver side returnerer opptil 100 elementer.

Gi denne dokumentasjonen til agenten din#

Hver side i dokumentasjonen har knappen Kopier siden, som kopierer siden som Markdown, klar til å lime inn i en AI-agent. Hver side er også tilgjengelig som ren Markdown, og hele API-referansen som én fil:

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

Gi agenten din den URL-en, eller koble den til direkte med MCP-serveren.