Prehľad API

Diaform API dáva vášmu kódu a vašim AI agentom prístup k spätnej väzbe, ktorú zbierate: k projektom, rozhovorom s AI zhrnutím a celým prepisom a k AI reportom. Využijete ho na analýzu odpovedí vlastným agentom, plnenie dátového skladu alebo spúšťanie automatizácií.

Pripojiť sa môžete dvoma spôsobmi. Oba používajú rovnaký API kľúč a vracajú rovnaké dáta:

• REST API. JSON cez HTTPS, pre skripty, backendy a automatizačné nástroje.
• MCP server. Pre AI agentov, ako sú Claude Code, Codex alebo Cursor. Agent dostane API ako nástroje, ktoré môže volať priamo. Viac v časti MCP server.

Čo môžete robiť#

Ak chcete dostať oznámenie, keď sa rozhovor skončí, a nechcete sa opakovane dopytovať, použite webhooky.

Skôr než začnete#

Potrebujete dve veci:

1. Plán Pro, Business alebo Enterprise.
2. API kľúč. Kľúče vytvárajú vlastníci a administrátori v časti Nastavenia → Všeobecné → API kľúče.

Kľúč vytvoríte tak, že kliknete na Nový API kľúč, zadáte názov a kliknete na Vytvoriť kľúč. V dialógu Váš nový API kľúč kliknite na Kopírovať a potom na Kľúč mám uložený. Diaform kľúč ukáže len raz.

Kľúče vyzerajú ako dia_org_live_ a za tým 32 znakov. Nevypršia. Každá organizácia ich môže mať najviac 10. Ak chcete kľúč vypnúť, kliknite na Odvolať a potom na Odvolať API kľúč. Všetko, čo kľúč používa, okamžite prestane fungovať.

Overenie#

Kľúč posielajte ako bearer token pri každej požiadavke:

Authorization: Bearer dia_org_live_...

Kľúč môže čítať všetky projekty vo svojej organizácii bez ohľadu na nastavenia prístupu k projektu. Majte ho na serveri alebo v konfigurácii svojho agenta a nikdy ho nedávajte do kódu v prehliadači ani v aplikácii. Príklady v tejto dokumentácii ho čítajú z premennej prostredia DIAFORM_API_KEY.

Základná URL a konvencie#

https://diaform.io/api/v1

• Požiadavky aj odpovede sú vo formáte JSON. Názvy polí používajú snake_case.
• ID sú UUID. Časové pečiatky sú reťazce ISO 8601 v UTC.
• Pole bez hodnoty je null. Nikdy sa nevynecháva.
• API označuje moderátora ako projekt, rovnako ako dashboard. ID projektu je ID za /agents/ v URL projektu v dashboarde a za /c/ v jeho verejnom odkaze.
• Rozhovory spustené cez Náhľad v dashboarde sa nikdy nevracajú.

Pošlite prvú požiadavku#

Vypíšte svoje projekty:

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

Potom načítajte dokončené rozhovory jedného z nich:

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"

Stránkovanie#

Endpointy so zoznamom vracajú položky od najnovších, v tomto tvare:

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

Ďalšiu stránku získate tak, že požiadavku zopakujete s rovnakými filtrami a do cursor dáte hodnotu next_cursor. Na poslednej stránke má has_more hodnotu false a next_cursor hodnotu 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;
}

Chyby#

Chyby používajú štandardné stavové kódy HTTP a vracajú JSON so zrozumiteľnou správou error a stabilným poľom code, podľa ktorého môžete chyby v kóde rozlíšiť:

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

Odpoveď 400 obsahuje aj details, jednu položku pre každé neplatné pole:

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

ID z inej organizácie vráti 404, rovnako ako ID, ktoré neexistuje.

Limity požiadaviek#

Každý API kľúč môže poslať 120 požiadaviek za minútu, spolu na endpointy na čítanie a na MCP server. Nad tento limit vracajú požiadavky 429 s hlavičkou Retry-After: 60. Každá stránka vráti najviac 100 položiek.

Dajte túto dokumentáciu svojmu agentovi#

Každá stránka dokumentácie má tlačidlo Skopírovať stránku, ktoré ju skopíruje ako Markdown, pripravený na vloženie do AI agenta. Každá stránka je dostupná aj ako čistý Markdown a celá referencia API ako jeden súbor:

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

Dajte svojmu agentovi túto URL alebo ho pripojte priamo cez MCP server.