Przegląd API

API Diaform daje Twojemu kodowi i Twoim agentom AI dostęp do opinii, które zbierasz: projektów, rozmów z podsumowaniami AI i pełnymi transkrypcjami oraz raportów AI. Możesz dzięki niemu analizować odpowiedzi własnym agentem, zasilać hurtownię danych albo uruchamiać automatyzacje.

Połączyć się możesz na dwa sposoby. Oba używają tego samego klucza API i zwracają te same dane:

REST API. JSON przez HTTPS, dla skryptów, backendów i narzędzi do automatyzacji.
Serwer MCP. Dla agentów AI, takich jak Claude Code, Codex czy Cursor. Agent dostaje API jako narzędzia, które może wywoływać bezpośrednio. Zobacz Serwer MCP.

Co możesz zrobić#

Zasób	Endpointy	Dokumentacja
Projekty	Lista projektów, pobranie jednego projektu z pytaniami	Projekty
Rozmowy	Lista rozmów w projekcie z podsumowaniami AI, pobranie jednej rozmowy z transkrypcją	Rozmowy
Raporty AI	Lista raportów w projekcie, pobranie całego raportu	Raporty
Zaproszenia respondentów	Utworzenie osobistego linku do wywiadu dla konkretnej osoby	Zaproszenia respondentów

Jeśli wolisz dostawać powiadomienie o zakończeniu rozmowy zamiast odpytywać API, użyj webhooków.

Zanim zaczniesz#

Potrzebujesz dwóch rzeczy:

Planu Pro, Business lub Enterprise.
Klucza API. Osoby z rolami Właściciel i Administrator tworzą klucze w Ustawienia → Ogólne → Klucze API.

Żeby utworzyć klucz, kliknij Nowy klucz API, nadaj mu nazwę i kliknij Utwórz klucz. W oknie Twój nowy klucz API kliknij Kopiuj, a potem Mam już zapisany klucz. Diaform pokazuje klucz tylko raz.

Klucze składają się z prefiksu dia_org_live_ i 32 znaków. Nie wygasają. Każda organizacja może mieć ich do 10. Żeby wyłączyć klucz, kliknij Unieważnij, a potem Unieważnij klucz API. Wszystko, co używa tego klucza, od razu przestaje działać.

Uwierzytelnianie#

Wysyłaj klucz jako token bearer w każdym żądaniu:

HTTP

Authorization: Bearer dia_org_live_...

Klucz może odczytać każdy projekt w swojej organizacji, niezależnie od ustawień dostępu do projektu. Trzymaj go na serwerze albo w konfiguracji agenta i nigdy nie umieszczaj w kodzie przeglądarki ani aplikacji. Przykłady w tej dokumentacji odczytują go ze zmiennej środowiskowej DIAFORM_API_KEY.

Bazowy URL i konwencje#

https://diaform.io/api/v1

Żądania i odpowiedzi są w formacie JSON. Nazwy pól są zapisane w snake_case.
ID mają format UUID. Znaczniki czasu to ciągi znaków ISO 8601 w UTC.
Pole bez wartości ma wartość null. Nigdy nie jest pomijane.
API nazywa prowadzącego wywiad projektem, tak jak panel. ID projektu to ID po /agents/ w adresie URL projektu w panelu i po /c/ w jego linku publicznym.
Rozmowy rozpoczęte w panelu przez Podgląd nigdy nie są zwracane.

Wyślij pierwsze żądanie#

Pobierz listę swoich projektów:

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

Potem pobierz zakończone rozmowy z jednego 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"

Paginacja#

Endpointy list zwracają elementy od najnowszych, w takiej postaci:

JSON

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

Parametr	Opis
`limit`	Liczba elementów na stronie, od 1 do 100. Domyślnie `25`.
`cursor`	Wartość `next_cursor` z poprzedniej strony

Żeby pobrać następną stronę, powtórz żądanie z tymi samymi filtrami i ustaw cursor na wartość next_cursor. Na ostatniej stronie has_more ma wartość false, a next_cursor to 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;
}

Błędy#

Błędy używają standardowych kodów statusu HTTP i zwracają JSON z czytelnym komunikatem error oraz stałą wartością code, na której możesz oprzeć obsługę błędów:

JSON

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

Odpowiedź 400 zawiera też details, po jednym wpisie na każde niepoprawne pole:

JSON

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

Status	`code`	Przyczyna
`400`	`invalid_request`	Brakuje parametru albo jest on niepoprawny. `details` wskazuje pole.
`401`	`unauthorized`	Brakuje nagłówka `Authorization`, nie ma on postaci `Bearer dia_org_live_...` albo klucz został unieważniony
`403`	`forbidden`	Twoja organizacja nie ma planu Pro, Business ani Enterprise
`404`	`not_found`	Takie ID nie istnieje w organizacji klucza
`429`	`rate_limited`	Za dużo żądań. Odczekaj tyle sekund, ile podaje nagłówek `Retry-After`.
`500`	`internal_error`	Wystąpił błąd po stronie Diaform. Spróbuj ponownie za chwilę.

ID z innej organizacji zwraca 404, tak samo jak ID, które nie istnieje.

Limity żądań#

Każdy klucz API może wysłać 120 żądań na minutę, łącznie do endpointów odczytu i serwera MCP. Po przekroczeniu limitu żądania zwracają 429 z nagłówkiem Retry-After: 60. Każda strona zwraca do 100 elementów.

Przekaż tę dokumentację swojemu agentowi#

Każda strona dokumentacji ma przycisk Kopiuj stronę, który kopiuje ją jako Markdown, gotowy do wklejenia agentowi AI. Każda strona jest też dostępna jako zwykły Markdown, a cała dokumentacja API jako jeden plik:

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

Podaj agentowi ten URL albo połącz go bezpośrednio przez serwer MCP.