Přehled API

Diaform API dává vašemu kódu a vašim AI agentům přístup ke zpětné vazbě, kterou sbíráte: k projektům, rozhovorům se shrnutím od AI a celým přepisem a k AI reportům. Využijete ho k analýze odpovědí vlastním agentem, plnění datového skladu nebo spouštění automatizací.

Připojit se můžete dvěma způsoby. Oba používají stejný API klíč a vracejí stejná data:

• REST API. JSON přes HTTPS, pro skripty, backendy a automatizační nástroje.
• MCP server. Pro AI agenty, jako jsou Claude Code, Codex nebo Cursor. Agent dostane API jako nástroje, které může volat přímo. Viz MCP server.

Co můžete dělat#

Pokud chcete dostat oznámení, když rozhovor skončí, a nechcete se opakovaně dotazovat, použijte webhooky.

Než začnete#

Potřebujete dvě věci:

1. Tarif Pro, Business nebo Enterprise.
2. API klíč. Klíče vytvářejí vlastníci a správci v části Nastavení → Obecné → API klíče.

Klíč vytvoříte kliknutím na Nový API klíč. Pojmenujte ho a klikněte na Vytvořit klíč. V dialogu Váš nový API klíč klikněte na Kopírovat a pak na Klíč mám uložený. Diaform klíč ukáže jen jednou.

Klíče vypadají jako dia_org_live_ následované 32 znaky. Nevyprší. Každá organizace jich může mít až 10. Klíč vypnete kliknutím na Zneplatnit a pak na Zneplatnit API klíč. Vše, co klíč používá, okamžitě přestane fungovat.

Ověření#

Klíč posílejte jako bearer token v každém požadavku:

Authorization: Bearer dia_org_live_...

Klíč může číst všechny projekty ve své organizaci bez ohledu na nastavení přístupu k projektu. Uchovávejte ho na serveru nebo v konfiguraci svého agenta a nikdy ho nedávejte do kódu v prohlížeči nebo v aplikaci. Příklady v této dokumentaci ho čtou z proměnné prostředí DIAFORM_API_KEY.

Základní URL a konvence#

https://diaform.io/api/v1

• Požadavky i odpovědi jsou ve formátu JSON. Názvy polí používají snake_case.
• ID jsou UUID. Časová razítka jsou řetězce ISO 8601 v UTC.
• Pole bez hodnoty je null. Nikdy se nevynechává.
• API označuje tazatele jako projekt, stejně jako dashboard. ID projektu je ID za /agents/ v URL projektu v dashboardu a za /c/ v jeho veřejném odkazu.
• Rozhovory spuštěné přes Náhled v dashboardu se nikdy nevracejí.

Pošlete první požadavek#

Vypište své projekty:

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

Pak načtěte dokončené rozhovory jednoho 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ánkování#

Endpointy s výpisem vracejí položky od nejnovějších, v tomto tvaru:

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

Další stránku získáte tak, že požadavek zopakujete se stejnými filtry a do cursor dáte hodnotu next_cursor. Na poslední stránce 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í standardní stavové kódy HTTP a vracejí JSON se srozumitelnou zprávou error a stabilním polem code, podle kterého můžete chyby v kódu rozlišit:

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

Odpověď 400 obsahuje také details, jednu položku na 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 jiné organizace vrátí 404, stejně jako ID, které neexistuje.

Limity požadavků#

Každý API klíč může poslat 120 požadavků za minutu, dohromady na endpointy pro čtení a na MCP server. Nad tento limit vracejí požadavky 429 s hlavičkou Retry-After: 60. Každá stránka vrátí až 100 položek.

Dejte tuto dokumentaci svému agentovi#

Každá stránka dokumentace má tlačítko Zkopírovat stránku, které ji zkopíruje jako Markdown, připravený k vložení do AI agenta. Každá stránka je dostupná i jako čistý Markdown a celá reference API jako jeden soubor:

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

Dejte svému agentovi tuto URL nebo ho připojte přímo přes MCP server.