Pregled API-ja

Diaform API vašem kodu i vašim AI agentima daje pristup povratnim informacijama koje prikupljate: projektima, razgovorima s AI sažecima i cijelim transkriptima te AI izvještajima. Koristite ga za analizu odgovora vlastitim agentom, punjenje skladišta podataka ili pokretanje automatizacija.

Povezati se možete na dva načina. Oba koriste isti API ključ i vraćaju iste podatke:

• REST API. JSON preko HTTPS-a, za skripte, pozadinske sustave i alate za automatizaciju.
• MCP poslužitelj. Za AI agente kao što su Claude Code, Codex ili Cursor. Agent dobiva API u obliku alata koje može izravno pozivati. Pogledajte MCP poslužitelj.

Što možete učiniti#

Da biste umjesto stalnog provjeravanja dobili obavijest kad razgovor završi, koristite webhookove.

Prije početka#

Potrebne su vam dvije stvari:

1. Paket Pro, Business ili Enterprise.
2. API ključ. Vlasnici i administratori izrađuju ključeve pod Postavke → Općenito → API ključevi.

Da biste izradili ključ, kliknite Novi API ključ, dajte mu naziv i kliknite Izradi ključ. U dijalogu Vaš novi API ključ kliknite Kopiraj, a zatim Ključ je spremljen. Diaform prikazuje ključ samo jednom.

Ključevi izgledaju kao dia_org_live_ nakon čega slijede 32 znaka. Ne istječu. Svaka organizacija može imati najviše 10 ključeva. Da biste ključ isključili, kliknite Opozovi, a zatim Opozovi API ključ. Sve što koristi taj ključ odmah prestaje raditi.

Autentifikacija#

Ključ šaljite kao bearer token u svakom zahtjevu:

Authorization: Bearer dia_org_live_...

Ključ može čitati svaki projekt u svojoj organizaciji, bez obzira na postavke pristupa projektu. Držite ga na poslužitelju ili u konfiguraciji svojeg agenta i nikad ga ne stavljajte u kod preglednika ili aplikacije. Primjeri u ovoj dokumentaciji čitaju ga iz varijable okruženja DIAFORM_API_KEY.

Osnovni URL i konvencije#

https://diaform.io/api/v1

• Zahtjevi i odgovori su u formatu JSON. Nazivi polja pišu se u obliku snake_case.
• ID-jevi su UUID-ovi. Vremenske oznake su znakovni nizovi u formatu ISO 8601, u UTC-u.
• Polje bez vrijednosti je null. Nikad se ne izostavlja.
• API intervjuera naziva projektom, kao i nadzorna ploča. ID projekta je ID nakon /agents/ u URL-u projekta na nadzornoj ploči i nakon /c/ u njegovoj javnoj poveznici.
• Razgovori pokrenuti kroz Pregled na nadzornoj ploči nikad se ne vraćaju.

Pošaljite prvi zahtjev#

Dohvatite popis svojih projekata:

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

Zatim dohvatite dovršene razgovore jednog od njih:

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"

Straničenje#

Krajnje točke za popise vraćaju stavke od najnovije, u ovom obliku:

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

Da biste dohvatili sljedeću stranicu, ponovite zahtjev s istim filtrima i postavite cursor na vrijednost next_cursor. Na zadnjoj stranici has_more je false, a next_cursor je 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;
}

Pogreške#

Pogreške koriste standardne HTTP statusne kodove i vraćaju JSON s čitljivom porukom error i stabilnom vrijednošću code na kojoj možete temeljiti obradu pogrešaka:

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

Odgovor 400 sadrži i details, po jedan unos za svako neispravno polje:

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

ID iz druge organizacije vraća 404, jednako kao i ID koji ne postoji.

Ograničenja broja zahtjeva#

Svaki API ključ može poslati 120 zahtjeva u minuti, ukupno prema krajnjim točkama za čitanje i MCP poslužitelju. Iznad toga zahtjevi vraćaju 429 sa zaglavljem Retry-After: 60. Svaka stranica vraća najviše 100 stavki.

Dajte ovu dokumentaciju svojem agentu#

Svaka stranica dokumentacije ima gumb Kopiraj stranicu koji je kopira kao Markdown, spreman za lijepljenje u AI agenta. Svaka je stranica dostupna i kao običan Markdown, a cijela dokumentacija API-ja kao jedna datoteka:

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

Uputite agenta na taj URL ili ga izravno povežite putem MCP poslužitelja.