Documentação da REST API

Autenticação

Crie uma chave de API em Configurações (até 3 chaves ativas). A chave em texto simples é mostrada apenas uma vez — guarde-a em segurança. Envie-a em cada pedido como um token Bearer:

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Pedidos sem uma chave válida e ativa recebem 401 Unauthorized. Se o plano da conta estiver inativo, os endpoints devolvem 403 Forbidden. As chaves podem ser rodada (invalida instantaneamente o segredo antigo) ou eliminadas a qualquer momento nas definições.

Convenções

Todos os pedidos e respostas usam application/json.
Respostas bem-sucedidas envolvem o conteúdo num data campo.
Os erros usam o envelope { "error": "<code>", "message": "<text>" }.
Os carimbos de data/hora são ISO‑8601 (UTC).

Endpoints

Método	Percurso	Descrição
`GET`	`/surveys`	Liste os seus questionários.
`POST`	`/surveys`	Crie um questionário.
`GET`	`/surveys/{id}`	Obtenha um questionário com as respetivas perguntas.
`PATCH`	`/surveys/{id}`	Atualize o título, descrição, estado, perguntas ou definições.
`DELETE`	`/surveys/{id}`	Elimine um questionário e todos os seus dados.
`GET`	`/surveys/{id}/responses`	Listar respostas (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Obter análise de IA em cache.
`POST`	`/surveys/{id}/analysis`	Gerar análise de IA para o questionário inteiro (necessita de ≥3 respostas).

Exemplos

Listar questionários

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  https://votira.co/api/v1/surveys

Criar questionário

curl -X POST https://votira.co/api/v1/surveys \
  -H "Authorization: Bearer $VOTIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pricing validation","description":"Quick check","questions":[]}'

Obter respostas (paginado)

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  "https://votira.co/api/v1/surveys/srv_123/responses?limit=50&offset=0"

Limites de taxa

Os pedidos são limitados por cliente. Os endpoints de leitura permitem até 600 pedidos/hora; as operações de escrita e análise de IA são mais restritas (a geração de IA está limitada a 30/hora). Se exceder um limite, será devolvido 429 com o rate_limited código de erro — aguarde e tente novamente.

Códigos de estado

200 / 201 — sucesso.
400 — corpo do pedido ou parâmetros inválidos.
401 — chave de API em falta ou inválida.
403 — plano de conta inativo.
404 — recurso não encontrado.
422 — dados insuficientes (por exemplo, menos de 3 respostas para análise).
429 — limite de taxa excedido.
502 — fornecedor de IA temporariamente indisponível.