Votira REST API

Acesso programático aos seus inquéritos, respostas e análise por IA. Versão v1.

URL base: https://votira.co/api/v1
Voltar às definições

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

  • Pedidos e respostas padrão usam JSON; exportações devolvem ficheiros CSV, JSON ou PDF para download.
  • 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étodoPercursoDescrição
GET/surveysListe os seus questionários.
POST/surveysCrie 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}/responsesListar respostas (?limit=, ?offset=).
GET/surveys/{id}/analysisObter análise de IA em cache.
POST/surveys/{id}/analysisGerar análise de IA para o questionário inteiro (necessita de ≥3 respostas).

Referência de integração avançada

O catálogo abaixo é gerado a partir da implementação ativa. Os parâmetros de consulta são usados em pedidos GET; outras operações aceitam um objeto JSON. Os identificadores de caminho são fornecidos no URL.

Consulte /api/v1/capabilities para esquemas legíveis por máquina. MCP create_survey e update_survey envolvem os campos do inquérito no payload; as operações REST aceitam esses campos diretamente.

Os inquéritos suportam até 50 perguntas e 20 páginas. Indique páginas, perguntas, definições, opensAt e closesAt nos pedidos de criação ou atualização. Os horários de agendamento requerem um fuso horário explícito. A publicação exige pelo menos uma pergunta.

Operações de IA podem devolver HTTP 202 com jobId; consulte /api/v1/ai/jobs/{job_id}. Leia /api/v1/ai/credits antes de operações pagas. Análises concluídas são reutilizadas até que o número de respostas mude; alterar o idioma não gera nova análise.

Exportações de respostas em CSV incluem até 5000 respostas completas; use offset para páginas adicionais. Relatórios em PDF incluem insights existentes sem gerar análise de IA paga. Respostas parciais têm um endpoint separado.

Para recolha externa de respostas, solicite a pré-visualização do inquérito com respondent_id e reutilize esse identificador ao submeter respostas associadas ao ID da pergunta. Isto mantém as variantes A/B consistentes. Nunca coloque uma chave API pessoal num cliente de browser público.

GET /capabilities

Ler operações disponíveis, esquemas, permissões e limites.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
POST /surveys/{survey_id}/duplicate

Duplicar um inquérito como novo rascunho sem respostas.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "title": {
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/status

Publicar, fechar ou devolver um inquérito para rascunho.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "status": {
      "enum": [
        "draft",
        "published",
        "closed"
      ]
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "status"
  ],
  "type": "object"
}
GET /templates

Listar modelos de inquérito localizados.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
GET /templates/{template_id}

Ler um modelo localizado com perguntas e tema.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "template_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "template_id"
  ],
  "type": "object"
}
POST /templates/{template_id}/surveys

Criar um inquérito localizado a partir de um modelo sem créditos de IA.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "template_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "title": {
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "template_id"
  ],
  "type": "object"
}
GET /question-types

Listar todos os tipos de perguntas suportados e campos de configuração específicos por tipo.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
POST /surveys/{survey_id}/questions

Adicionar uma pergunta ao inquérito.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "question": {
      "type": "object"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question"
  ],
  "type": "object"
}
PATCH /surveys/{survey_id}/questions/{question_id}

Atualizar uma pergunta mantendo a sua identidade.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "question": {
      "type": "object"
    },
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id",
    "question"
  ],
  "type": "object"
}
DELETE /surveys/{survey_id}/questions/{question_id}

Eliminar uma pergunta e reparar referências de ramificação.

Permissões necessárias: delete

{
  "additionalProperties": false,
  "properties": {
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/questions/reorder

Reordenar todas as perguntas, mantendo a ordem principal das páginas.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "order": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 50,
      "type": "array",
      "uniqueItems": true
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "order"
  ],
  "type": "object"
}
GET /surveys/{survey_id}/preview

Obter perguntas A/B resolvidas sem registar uma visualização. Use respondent_id para corresponder às submissões JSON seguintes.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "seed": {
      "maxLength": 2000,
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}
POST /ai/questions

Gerar perguntas a partir de uma ideia ou editar perguntas existentes de forma incremental. Custa um crédito; pode devolver um trabalho.

Permissões necessárias: write, ai

{
  "additionalProperties": false,
  "properties": {
    "idea": {
      "maxLength": 2000,
      "type": "string"
    },
    "pages": {
      "items": {
        "type": "object"
      },
      "maxItems": 20,
      "type": "array"
    },
    "questions": {
      "items": {
        "type": "object"
      },
      "maxItems": 50,
      "type": "array"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "idea"
  ],
  "type": "object"
}
GET /ai/jobs/{job_id}

Ler o estado e resultado de um trabalho de IA pertencente a esta conta.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "job_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/questions/{question_id}/analysis

Analisar uma pergunta de texto livre. Resultados em cache são gratuitos; nova análise custa um crédito.

Permissões necessárias: write, ai

{
  "additionalProperties": false,
  "properties": {
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id"
  ],
  "type": "object"
}
GET /ai/credits

Ler créditos de IA disponíveis, plafond, consumo e custos das operações.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
GET /ai-panel/personas

Listar personas num painel pessoal ou de organização, opcionalmente restrito a um grupo.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
GET /ai-panel/personas/{persona_id}

Ler uma persona sintética.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}
POST /ai-panel/personas

Criar uma persona manualmente sem consumir créditos de IA.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "attributes": {
      "type": "object"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "poolIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}
PATCH /ai-panel/personas/{persona_id}

Editar atributos da persona e substituir grupos quando fornecido.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "attributes": {
      "type": "object"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "poolIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}
DELETE /ai-panel/personas/{persona_id}

Eliminar uma persona do painel.

Permissões necessárias: delete

{
  "additionalProperties": false,
  "properties": {
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}
GET /ai-panel/pools

Listar grupos nomeados e o número de personas em cada um.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
GET /ai-panel/pools/{pool_id}

Ler um grupo nomeado e as suas personas.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}
POST /ai-panel/pools

Criar um grupo de personas nomeado.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}
PATCH /ai-panel/pools/{pool_id}

Renomear um grupo ou atualizar a sua descrição.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}
DELETE /ai-panel/pools/{pool_id}

Eliminar um grupo e desvincular os seus membros sem eliminar as personas.

Permissões necessárias: delete

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}
POST /ai-panel/pools/{pool_id}/members

Adicionar ou remover personas em massa de um grupo.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "add",
        "remove"
      ]
    },
    "personaIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "personaIds",
    "action"
  ],
  "type": "object"
}
POST /ai-panel/import

Importar personas de JSON. Metadados dos grupos são ignorados; personas importadas ficam por atribuir.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "personas": {
      "items": {
        "type": "object"
      },
      "maxItems": 200,
      "minItems": 1,
      "type": "array"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "personas"
  ],
  "type": "object"
}
GET /ai-panel/export

Exportar personas ou um grupo como JSON ou CSV.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "format": {
      "enum": [
        "json",
        "csv"
      ]
    },
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
POST /ai-panel/generate

Gerar personas com IA. Custa cinco créditos por persona, com reembolso para resultados em falta.

Permissões necessárias: write, ai

{
  "additionalProperties": false,
  "properties": {
    "ageMax": {
      "maximum": 120,
      "minimum": 13,
      "type": "integer"
    },
    "ageMin": {
      "maximum": 120,
      "minimum": 13,
      "type": "integer"
    },
    "count": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "extra": {
      "maxLength": 2000,
      "type": "string"
    },
    "genderMix": {
      "additionalProperties": false,
      "properties": {
        "female": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        },
        "male": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        },
        "non_binary": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "description"
  ],
  "type": "object"
}
GET /ai-panel/cost

Estimar créditos necessários para administrar um inquérito a um grupo nomeado.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "survey_id"
  ],
  "type": "object"
}
POST /ai-panel/administer

Administrar um inquérito a um grupo nomeado. Custa três créditos por persona; pode devolver um trabalho.

Permissões necessárias: write, ai

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "survey_id"
  ],
  "type": "object"
}
GET /surveys/{survey_id}/results

Ler estatísticas por pergunta, análises A/B, visualizações, contagens do painel de IA e análise de desistências.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}
GET /surveys/{survey_id}/partial-responses

Ler respostas em andamento, separadamente das submissões concluídas.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}
GET /surveys/{survey_id}/export

Descarregar respostas concluídas em CSV (até 5000 por página) ou um relatório de resultados em PDF.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "format": {
      "enum": [
        "csv",
        "pdf"
      ]
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/images

Carregar uma imagem PNG, JPEG, GIF ou WebP codificada em base64 (máximo 5 MB) para o tema do inquérito.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "content": {
      "maxLength": 6990510,
      "type": "string"
    },
    "contentType": {
      "enum": [
        "image/png",
        "image/jpeg",
        "image/gif",
        "image/webp"
      ]
    },
    "field": {
      "enum": [
        "headerImage",
        "backgroundImage"
      ]
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "field",
    "contentType",
    "content"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/responses

Submeter uma resposta concluída para um respondente externo; aplica regras de publicação, agendamento, ramificação e duplicados.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "answers": {
      "type": "object"
    },
    "completionTimeSeconds": {
      "maximum": 604800,
      "minimum": 0,
      "type": "integer"
    },
    "respondentInfo": {
      "type": "object"
    },
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "respondent_id",
    "answers"
  ],
  "type": "object"
}
POST /surveys/{survey_id}/partial-responses

Guardar automaticamente uma resposta parcial de um respondente externo quando a recolha está ativada.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "answers": {
      "type": "object"
    },
    "completionTimeSeconds": {
      "maximum": 604800,
      "minimum": 0,
      "type": "integer"
    },
    "respondentInfo": {
      "type": "object"
    },
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "respondent_id",
    "answers"
  ],
  "type": "object"
}
GET /account

Ler perfil, idioma, domínio, plano e acesso à organização.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
PATCH /account

Atualizar nome de exibição, idioma do serviço ou domínio personalizado. Não altera o email, credenciais ou faturação.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "customDomain": {
      "maxLength": 253,
      "type": [
        "string",
        "null"
      ]
    },
    "displayName": {
      "maxLength": 100,
      "minLength": 2,
      "type": "string"
    },
    "preferredLanguage": {
      "maxLength": 10,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
GET /organization

Ler a organização, licenças disponíveis e créditos de IA partilhados.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
GET /organization/members

Listar membros da organização, funções, licenças e consumo de IA. Apenas administradores.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
POST /organization/members

Adicionar uma conta Votira existente à organização. Apenas administradores.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "email": {
      "maxLength": 254,
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    }
  },
  "required": [
    "email",
    "role"
  ],
  "type": "object"
}
PATCH /organization/members/{member_id}

Atualizar a função ou licença atribuída de um membro. Apenas administradores; o proprietário está protegido.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "hasLicense": {
      "type": "boolean"
    },
    "member_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}
DELETE /organization/members/{member_id}

Remover um membro sem eliminar a sua conta. Apenas administradores.

Permissões necessárias: delete

{
  "additionalProperties": false,
  "properties": {
    "member_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}
GET /organization/invites

Listar convites da organização sem expor os tokens de convite. Apenas administradores.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
POST /organization/invites

Criar um convite e devolver o URL de partilha. Apenas administradores.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "email": {
      "maxLength": 254,
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    },
    "type": {
      "enum": [
        "member",
        "guest"
      ]
    }
  },
  "required": [
    "role"
  ],
  "type": "object"
}
DELETE /organization/invites/{invite_id}

Revogar um convite pendente da organização. Apenas administradores.

Permissões necessárias: delete

{
  "additionalProperties": false,
  "properties": {
    "invite_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "invite_id"
  ],
  "type": "object"
}
GET /audit-log

Pesquisar o registo de auditoria da organização. Apenas administradores Enterprise.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "auth",
        "survey",
        "results",
        "ai",
        "keys",
        "billing",
        "organization",
        "profile",
        "audit",
        "api",
        "mcp"
      ]
    },
    "date_from": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "date_to": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "search": {
      "maxLength": 100,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
GET /audit-log/export

Exportar até 5000 registos de auditoria em CSV. Apenas administradores Enterprise.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "auth",
        "survey",
        "results",
        "ai",
        "keys",
        "billing",
        "organization",
        "profile",
        "audit",
        "api",
        "mcp"
      ]
    },
    "date_from": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "date_to": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "search": {
      "maxLength": 100,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
GET /billing/invoices

Listar faturas pessoais pagas e, para administradores, faturas da organização.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}
GET /billing/invoices/{invoice_id}/pdf

Descarregar o PDF de uma fatura paga após verificar a titularidade da faturação.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "invoice_id": {
      "maxLength": 100,
      "pattern": "^in_[A-Za-z0-9]+$",
      "type": "string"
    }
  },
  "required": [
    "invoice_id"
  ],
  "type": "object"
}
GET /support

Listar os pedidos de suporte, relatórios de erros e pedidos de funcionalidades da conta.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}
GET /support/{submission_id}

Ler um pedido de suporte e respostas da equipa, restrito ao seu proprietário.

Permissões necessárias: read

{
  "additionalProperties": false,
  "properties": {
    "submission_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "submission_id"
  ],
  "type": "object"
}
POST /support

Abrir um pedido de suporte, relatório de erro ou pedido de funcionalidade.

Permissões necessárias: write

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "bug",
        "feature",
        "ticket"
      ]
    },
    "description": {
      "maxLength": 5000,
      "minLength": 10,
      "type": "string"
    },
    "priority": {
      "enum": [
        "low",
        "normal",
        "high",
        "urgent"
      ]
    },
    "problemSolved": {
      "maxLength": 5000,
      "type": "string"
    },
    "severity": {
      "enum": [
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "stepsToReproduce": {
      "maxLength": 5000,
      "type": "string"
    },
    "subject": {
      "maxLength": 150,
      "minLength": 3,
      "type": "string"
    },
    "ticketCategory": {
      "enum": [
        "billing",
        "technical",
        "account",
        "other"
      ]
    }
  },
  "required": [
    "category",
    "subject",
    "description"
  ],
  "type": "object"
}

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.
  • 202 — Pedido de IA aceite; consulte o estado.
  • 402 — Sem créditos de IA disponíveis.
  • 409 — A operação entra em conflito com o estado atual do recurso.
  • 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.

Pare de adivinhar. Comece a validar.

Crie o seu primeiro inquérito com IA em minutos e descubra se a sua ideia tem potencial.

Iniciar Teste Gratuito

Teste gratuito de 7 dias com todas as funcionalidades · Não é necessário cartão de crédito