API

Atualizado 20 de outubro de 2026

Nesta página

A API REST do SurveyNinja permite que os seus aplicativos trabalhem com pesquisas e respostas: obter a lista de pesquisas, ler respostas, exportá-las e gerenciar variáveis ocultas e webhooks. A API retorna JSON.

Este artigo cobre o básico. A referência completa com todos os endpoints e parâmetros está em surveyninja.io/dev/api.

Antes de começar

Uma chave API pertence à conta do dono do espaço de trabalho: as solicitações feitas com a chave têm o mesmo acesso que o dono. No espaço de trabalho de outra pessoa, a seção API / MCP só abre se a sua função tiver acesso a ela, e as chaves que você criar lá são adicionadas à conta do dono.

Criar uma chave API

Clique no ícone do seu perfil no canto superior direito e escolha API / MCP.
Clique em Gerar chave API (1).
Na janela Gerar nova chave API, digite o Nome da chave (pelo menos 3 caracteres), por exemplo "CRM sync", e clique em Criar chave.
Copie a chave e guarde-a em um lugar seguro. Depois clique em Eu salvei a chave, fechar a janela.

Importante. A chave é mostrada só uma vez. Se você a perder, exclua-a e crie uma nova.

A lista mostra os últimos caracteres de cada chave e quando ela foi criada (Criado) e usada pela última vez (Último uso). Para renomear ou excluir uma chave, abra o menu (2) ao lado dela e escolha Renomear ou Excluir. Para excluir, confirme na janela Excluir chave da API. Para que um aplicativo deixe de usar a API, exclua a chave dele: as solicitações com uma chave excluída recebem o código 401.

Fazer solicitações

Todas as solicitações vão para esta URL base:

https://api.surveyninja.io/api/v3/service

Passe a chave no cabeçalho Authorization de cada solicitação:

Authorization: Bearer YOUR_API_KEY

Por exemplo, esta solicitação retorna a lista das suas pesquisas:

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Se a chave estiver ausente ou errada, a API responde com o código 401.

As integrações feitas com os caminhos antigos da API (/api/service) também funcionam com as chaves novas. Para integrações novas, use a API v3.

Principais endpoints

Os caminhos são relativos à URL base.

Método	Caminho	O que faz
GET	/user	Informações sobre o dono da chave
GET	/workspaces	Os seus espaços de trabalho
GET	/folders	Pastas do seu espaço de trabalho
GET	/quiz	Lista de pesquisas
GET	/quiz/{id}	Dados e perguntas da pesquisa
POST	/quiz	Criar uma pesquisa
POST	/quiz/{id}/publish	Publicar uma pesquisa
GET	/quiz/{id}/answers	Lista de respostas
GET	/quiz/{id}/answers/csv	Respostas em um arquivo CSV
GET	/quiz/{id}/answers/xlsx	Respostas em um arquivo do Excel
GET	/quiz/{id}/summary	Resumo: visitas, respostas completas, taxa de conclusão
GET	/quiz/{id}/hidden/variables	Variáveis ocultas de uma pesquisa
GET	/quiz/{id}/webhooks	Webhooks de uma pesquisa

A API também cobre as configurações da pesquisa, temas, pastas, participantes, códigos promocionais, links únicos e relatórios. Veja a lista completa na referência da API.

Obter a lista de pesquisas

GET /quiz aceita estes parâmetros de consulta:

Parâmetro	Descrição
limit, offset	Paginação
sort	created_at, updated_at, name ou id. Padrão: id
order	desc ou asc. Padrão: desc
folder_id	Retorna só as pesquisas de uma pasta

A resposta é um array com as pesquisas do espaço de trabalho do dono da chave. Sem limit, ela traz todas. Cada pesquisa tem id, name, type, url_shared (o link público), is_published, created_at, updated_at, folder e notes.

Obter respostas

GET /quiz/{id}/answers retorna as respostas de uma pesquisa, por padrão das mais recentes para as mais antigas.

Parâmetro	Descrição
limit	Número de respostas, até 100. Padrão: 20
offset	Quantas respostas pular. Padrão: 0
date	Respostas de um dia, no formato YYYY-MM-DD
is_complete	true para só respostas completas, false para as incompletas
sort	date_start ou date_end
order	desc ou asc

Exemplo de solicitação:

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/answers?limit=50&amp;is_complete=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Exemplo de resposta (resumido):

{
  "answers": [
    {
      "id": 4813,
      "visit_id": 46139,
      "date": "2026-08-24T12:51:33",
      "date_start": "2026-08-24T12:50:52",
      "date_end": "2026-08-24T12:51:33",
      "filling_time_seconds": 41,
      "extra_fields": { "utm_source": "newsletter" },
      "is_complete": true,
      "is_respondent": false,
      "answers": [
        {
          "type": "input",
          "rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
          "title": "O que devemos melhorar?",
          "result": "Suporte mais rápido",
          "min_val": null,
          "max_val": null,
          "hidden_options": null
        },
        {
          "type": "userInfo",
          "title": "User info",
          "result": {
            "ip": "203.0.113.10",
            "browser": "Chrome",
            "country": "Germany",
            "user_agent": "Mozilla/5.0 ...",
            "password_number": null,
            "import_source": null,
            "is_anonymous": false
          },
          "is_anonymous": false
        }
      ],
      "over_upload_limit": false,
      "unique_link": null
    }
  ],
  "answer_total_count": 128
}

Em cada resposta, answers contém um objeto por pergunta. rowId é o ID da pergunta e result é a resposta. O último objeto, do tipo userInfo, traz os dados técnicos do respondente. Em pesquisas anônimas, o endereço IP, o navegador, o país e o user agent vêm como null. Se nenhuma resposta corresponder à solicitação, answers vem como null.

answer_total_count é o número total de respostas da pesquisa, incluindo as incompletas e as desqualificadas. Os filtros date e is_complete não o alteram, então não o use para contar as páginas de uma solicitação filtrada.

MCP para assistentes de IA

A mesma chave API conecta o SurveyNinja a assistentes de IA compatíveis com o Model Context Protocol (MCP), como Claude ou Cursor. O MCP está disponível em todos os planos, inclusive no Grátis. Como configurar está descrito em Conectar assistentes de IA (MCP).

Limites

Uma conta pode ter até 5 chaves API.
GET /quiz/{id}/answers retorna até 100 respostas por solicitação. Para obter o restante, use limit e offset.
GET /quiz/{id}/answers não retorna respostas desqualificadas nem excluídas.
O nome de uma chave precisa ter pelo menos 3 caracteres.

Se algo não funcionar

A API responde com o código 401. A chave está ausente, foi digitada errado ou foi excluída. Confira o cabeçalho: a palavra Bearer, um espaço e a chave.
"Você excedeu o limite de criação de chaves da API" ao clicar em Gerar chave API. A conta já tem 5 chaves. Mudar para um plano superior não aumenta esse limite. Exclua uma chave que você não usa mais.
A API retorna só 20 respostas. Esse é o limite padrão. Passe limit (até 100) e offset para obter mais.

API