Descripción general de la API

La API de Diaform da a tu propio código y a tus agentes de IA acceso al feedback que recopilas: proyectos, conversaciones con sus resúmenes de IA y transcripciones completas, e informes de IA. Úsala para analizar las respuestas con tu propio agente, alimentar un almacén de datos o activar automatizaciones.

Hay dos formas de conectarte, y las dos usan la misma clave de API y devuelven los mismos datos:

• API REST. JSON por HTTPS, para scripts, backends y herramientas de automatización.
• Servidor MCP. Para agentes de IA como Claude Code, Codex o Cursor. El agente recibe la API como herramientas que puede llamar directamente. Consulta Servidor MCP.

Qué puedes hacer#

Para recibir un aviso cuando termina una conversación, en lugar de consultar la API cada cierto tiempo, usa los webhooks.

Antes de empezar#

Necesitas dos cosas:

1. Un plan Pro, Business o Enterprise.
2. Una clave de API. Los propietarios y los administradores crean claves en Configuración → General → Claves de API.

Para crear una clave, haz clic en Nueva clave de API, ponle un nombre y haz clic en Crear clave. En el cuadro de diálogo Tu nueva clave de API, haz clic en Copiar y después en Ya guardé mi clave. Diaform muestra la clave una sola vez.

Las claves tienen el formato dia_org_live_ seguido de 32 caracteres. No caducan. Cada organización puede tener hasta 10. Para desactivar una, haz clic en Revocar y después en Revocar clave de API. Todo lo que use la clave deja de funcionar al instante.

Autenticación#

Envía la clave como token bearer en cada solicitud:

Authorization: Bearer dia_org_live_...

Una clave puede leer todos los proyectos de su organización, sea cual sea la configuración de acceso del proyecto. Guárdala en tu servidor o en la configuración de tu agente, y nunca la pongas en el código del navegador ni de una app. Los ejemplos de esta documentación la leen de una variable de entorno DIAFORM_API_KEY.

URL base y convenciones#

https://diaform.io/api/v1

• Las solicitudes y las respuestas son JSON. Los nombres de los campos usan snake_case.
• Los ID son UUID. Las marcas de tiempo son cadenas ISO 8601 en UTC.
• Un campo sin valor es null. Nunca se omite.
• La API llama proyecto al entrevistador, igual que el panel. El ID de un proyecto es el ID que va después de /agents/ en la URL del proyecto en el panel, y después de /c/ en su enlace público.
• Las conversaciones iniciadas desde la Vista previa del panel no se devuelven nunca.

Hacer tu primera solicitud#

Lista tus proyectos:

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

Después, obtén las conversaciones completadas de uno de ellos:

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"

Paginación#

Los endpoints de lista devuelven primero los elementos más recientes, con esta estructura:

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

Para obtener la página siguiente, repite la solicitud con los mismos filtros y pon en cursor el valor de next_cursor. En la última página, has_more es false y next_cursor es 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;
}

Errores#

Los errores usan los códigos de estado HTTP estándar y devuelven JSON con un mensaje legible en error y un code estable que puedes usar en tu código para distinguir cada caso:

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

Un 400 también incluye details, con una entrada por cada campo no válido:

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

Un ID de otra organización devuelve 404, igual que uno que no existe.

Límites de solicitudes#

Cada clave de API puede hacer 120 solicitudes por minuto, sumando los endpoints de lectura y el servidor MCP. Por encima de ese límite, las solicitudes devuelven 429 con una cabecera Retry-After: 60. Cada página devuelve hasta 100 elementos.

Dar esta documentación a tu agente#

Cada página de la documentación tiene un botón Copiar página que la copia en Markdown, lista para pegarla en un agente de IA. Cada página también está disponible como texto Markdown, y toda la referencia de la API en un solo archivo:

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

Dale esa URL a tu agente, o conéctalo directamente con el servidor MCP.