Panoramica dell’API

L’API di Diaform dà al tuo codice e ai tuoi agenti IA l’accesso al feedback che raccogli: i progetti, le conversazioni con i loro riepiloghi IA e le trascrizioni complete, e i report IA. Usala per analizzare le risposte con il tuo agente, alimentare un data warehouse o avviare automazioni.

Puoi collegarti in due modi. Entrambi usano la stessa chiave API e restituiscono gli stessi dati:

• API REST. JSON su HTTPS, per script, backend e strumenti di automazione.
• Server MCP. Per agenti IA come Claude Code, Codex o Cursor. L’agente riceve l’API sotto forma di strumenti che può chiamare direttamente. Vedi Server MCP.

Cosa puoi fare#

Per ricevere una notifica quando una conversazione finisce, senza interrogare l’API a intervalli regolari, usa i webhook.

Prima di iniziare#

Ti servono due cose:

1. Un piano Pro, Business o Enterprise.
2. Una chiave API. Proprietari e amministratori creano le chiavi in Impostazioni → Generali → Chiavi API.

Per creare una chiave, clicca Nuova chiave API, dalle un nome e clicca Crea chiave. Nella finestra La tua nuova chiave API, clicca Copia, poi Ho salvato la chiave. Diaform mostra la chiave una sola volta.

Le chiavi hanno il formato dia_org_live_ seguito da 32 caratteri. Non scadono. Ogni organizzazione può averne fino a 10. Per disattivarne una, clicca Revoca, poi Revoca chiave API. Tutto ciò che usa quella chiave smette subito di funzionare.

Autenticazione#

Invia la chiave come bearer token in ogni richiesta:

Authorization: Bearer dia_org_live_...

Una chiave può leggere tutti i progetti della sua organizzazione, qualunque siano le impostazioni di accesso del progetto. Tienila sul tuo server o nella configurazione del tuo agente, e non metterla mai nel codice del browser o dell’app. Gli esempi di questa documentazione la leggono da una variabile d’ambiente DIAFORM_API_KEY.

URL di base e convenzioni#

https://diaform.io/api/v1

• Richieste e risposte sono in JSON. I nomi dei campi usano lo snake_case.
• Gli ID sono UUID. I timestamp sono stringhe ISO 8601 in UTC.
• Un campo senza valore è null. Non viene mai omesso.
• L’API chiama un intervistatore progetto, come la dashboard. L’ID di un progetto è l’ID dopo /agents/ nell’URL del progetto nella dashboard, e dopo /c/ nel suo link pubblico.
• Le conversazioni avviate dall’Anteprima della dashboard non vengono mai restituite.

Fai la tua prima richiesta#

Elenca i tuoi progetti:

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

Poi recupera le conversazioni completate di uno di questi:

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"

Paginazione#

Gli endpoint di elenco restituiscono prima gli elementi più recenti, in questo formato:

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

Per ottenere la pagina successiva, ripeti la richiesta con gli stessi filtri e con cursor impostato su next_cursor. Nell’ultima pagina, has_more è false e next_cursor è 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;
}

Errori#

Gli errori usano i codici di stato HTTP standard e restituiscono un JSON con un messaggio error leggibile e un code stabile, che il tuo codice può controllare:

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

Un 400 ha anche details, con una voce per ogni campo non valido:

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

Un ID di un’altra organizzazione restituisce 404, come un ID che non esiste.

Limiti di frequenza#

Ogni chiave API può fare 120 richieste al minuto, sommando gli endpoint di lettura e il server MCP. Oltre questo limite, le richieste restituiscono 429 con un header Retry-After: 60. Ogni pagina restituisce fino a 100 elementi.

Dai questa documentazione al tuo agente#

Ogni pagina della documentazione ha un pulsante Copia pagina che la copia in Markdown, pronta da incollare in un agente IA. Ogni pagina è disponibile anche come semplice Markdown, e l’intero riferimento dell’API in un unico file:

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

Indica questo URL al tuo agente, oppure collegalo direttamente con il server MCP.