API-översikt

Diaforms API ger din egen kod och dina AI-agenter åtkomst till den feedback du samlar in: projekt, konversationer med AI-sammanfattningar och fullständiga transkriptioner, samt AI-rapporter. Använd det för att analysera svar med din egen agent, fylla ett datalager eller starta automatiseringar.

Det finns två sätt att ansluta, och båda använder samma API-nyckel och returnerar samma data:

• REST-API. JSON över HTTPS, för skript, backends och automatiseringsverktyg.
• MCP-server. För AI-agenter som Claude Code, Codex eller Cursor. Agenten får API:t som verktyg som den kan anropa direkt. Läs mer under MCP-server.

Det här kan du göra#

Använd webhooks för att få besked när en konversation avslutas, i stället för att fråga API:t med jämna mellanrum.

Innan du börjar#

Du behöver två saker:

1. Planen Pro, Business eller Enterprise.
2. En API-nyckel. Ägare och admins skapar nycklar under Inställningar → Allmänt → API-nycklar.

För att skapa en nyckel klickar du på Ny API-nyckel, ger den ett namn och klickar på Skapa nyckel. Klicka på Kopiera i dialogen Din nya API-nyckel och sedan på Jag har sparat nyckeln. Diaform visar nyckeln bara en gång.

Nycklarna ser ut som dia_org_live_ följt av 32 tecken. De går inte ut. Varje organisation kan ha upp till 10. För att stänga av en nyckel klickar du på Återkalla och sedan på Återkalla API-nyckel. Allt som använder nyckeln slutar fungera direkt.

Autentisering#

Skicka nyckeln som en bearer-token i varje förfrågan:

Authorization: Bearer dia_org_live_...

En nyckel kan läsa alla projekt i sin organisation, oavsett projektets åtkomstinställningar. Behåll den på din server eller i din agents konfiguration, och lägg den aldrig i kod som körs i webbläsaren eller i en app. Exemplen i den här dokumentationen läser den från miljövariabeln DIAFORM_API_KEY.

Bas-URL och konventioner#

https://diaform.io/api/v1

• Förfrågningar och svar är JSON. Fältnamn skrivs i snake_case.
• ID:n är UUID:er. Tidsstämplar är ISO 8601-strängar i UTC.
• Ett fält utan värde är null. Det utelämnas aldrig.
• API:t kallar en intervjuare för ett projekt, precis som dashboarden. Ett projekt-ID är ID:t efter /agents/ i projektets URL i dashboarden och efter /c/ i dess publika länk.
• Konversationer som startas från Förhandsvisa i dashboarden returneras aldrig.

Gör din första förfrågan#

Lista dina projekt:

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

Hämta sedan de slutförda konversationerna 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#

Endpoints som listar returnerar de nyaste posterna först, i det här formatet:

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

För att hämta nästa sida upprepar du förfrågan med samma filter och med cursor satt till next_cursor. På sista sidan har has_more värdet false och next_cursor värdet 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;
}

Fel#

Fel använder vanliga HTTP-statuskoder och returnerar JSON med ett läsbart error-meddelande och en stabil code som din kod kan agera på:

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

En 400 har också details, med en post per ogiltigt fält:

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

Ett ID från en annan organisation returnerar 404, precis som ett ID som inte finns.

Hastighetsbegränsningar#

Varje API-nyckel kan göra 120 förfrågningar per minut till de läsande endpointsen och MCP-servern sammanlagt. Över den gränsen returnerar förfrågningarna 429 med headern Retry-After: 60. Varje sida returnerar upp till 100 poster.

Ge dokumentationen till din agent#

Varje sida i dokumentationen har knappen Kopiera sidan, som kopierar sidan som Markdown, redo att klistra in i en AI-agent. Varje sida finns också som ren Markdown, och hela API-referensen som en enda fil:

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

Ge din agent den URL:en, eller anslut den direkt med MCP-servern.