Visão geral da API

A API do Diaform dá ao seu código e aos seus agentes de IA acesso ao feedback que você coleta: projetos, conversas com os resumos da IA e as transcrições completas, e relatórios de IA. Use para analisar respostas com seu próprio agente, alimentar um data warehouse ou disparar automações.

Há duas formas de se conectar, e as duas usam a mesma chave de API e retornam os mesmos dados:

• API REST. JSON via HTTPS, para scripts, backends e ferramentas de automação.
• Servidor MCP. Para agentes de IA como Claude Code, Codex ou Cursor. O agente recebe a API como ferramentas que ele pode chamar diretamente. Veja Servidor MCP.

O que você pode fazer#

Para ser avisado quando uma conversa termina, em vez de consultar a API de tempos em tempos, use os webhooks.

Antes de começar#

Você precisa de duas coisas:

1. Um plano Pro, Business ou Enterprise.
2. Uma chave de API. Proprietários e admins criam chaves em Configurações → Geral → Chaves de API.

Para criar uma chave, clique em Nova chave de API, dê um nome a ela e clique em Criar chave. Na janela Sua nova chave de API, clique em Copiar e depois em Já salvei minha chave. O Diaform mostra a chave uma única vez.

As chaves têm o formato dia_org_live_ seguido de 32 caracteres. Elas não expiram. Cada organização pode ter até 10. Para desativar uma, clique em Revogar e depois em Revogar chave de API. Tudo o que usa a chave para de funcionar imediatamente.

Autenticação#

Envie a chave como bearer token em toda requisição:

Authorization: Bearer dia_org_live_...

Uma chave pode ler todos os projetos da organização dela, sejam quais forem as configurações de acesso do projeto. Mantenha a chave no seu servidor ou na configuração do seu agente e nunca a coloque em código de navegador ou de app. Os exemplos desta documentação leem a chave de uma variável de ambiente DIAFORM_API_KEY.

URL base e convenções#

https://diaform.io/api/v1

• As requisições e as respostas são JSON. Os nomes dos campos usam snake_case.
• Os IDs são UUIDs. Os timestamps são strings ISO 8601 em UTC.
• Um campo sem valor é null. Ele nunca é omitido.
• A API chama o entrevistador de projeto, como o painel. O ID de um projeto é o ID que vem depois de /agents/ na URL do projeto no painel e depois de /c/ no link público.
• Conversas iniciadas pela Prévia do painel nunca são retornadas.

Fazer sua primeira requisição#

Liste seus projetos:

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

Depois, busque as conversas concluídas de um deles:

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"

Paginação#

Os endpoints de lista retornam primeiro os itens mais recentes, neste formato:

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

Para buscar a próxima página, repita a requisição com os mesmos filtros e com cursor igual a next_cursor. Na última página, 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;
}

Erros#

Os erros usam os códigos de status HTTP padrão e retornam JSON com uma mensagem legível em error e um code estável que você pode usar no seu código para tratar cada caso:

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

Um 400 também traz details, com um item para cada campo inválido:

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

Um ID de outra organização retorna 404, igual a um ID que não existe.

Limites de requisições#

Cada chave de API pode fazer 120 requisições por minuto, somando os endpoints de leitura e o servidor MCP. Acima disso, as requisições retornam 429 com um cabeçalho Retry-After: 60. Cada página retorna até 100 itens.

Dar esta documentação ao seu agente#

Toda página da documentação tem um botão Copiar página que copia a página em Markdown, pronta para colar em um agente de IA. Cada página também está disponível como texto Markdown, e a referência completa da API em um único arquivo:

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

Aponte seu agente para essa URL ou conecte-o diretamente com o servidor MCP.