Documentación de la REST API

Autenticación

Crea una clave API en Configuración (hasta 3 claves activas). La clave en texto plano solo se muestra una vez — guárdala de forma segura. Envíala en cada solicitud como un token Bearer:

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Las solicitudes sin una clave válida y activa reciben 401 Unauthorized. Si el plan de la cuenta está inactivo, los endpoints devuelven 403 Forbidden. Las claves pueden ser rotada (invalida instantáneamente el secreto anterior) o eliminadas en cualquier momento desde Configuración.

Convenciones

Todas las solicitudes y respuestas usan application/json.
Las respuestas exitosas envuelven el contenido en un data campo.
Los errores usan el sobre { "error": "<code>", "message": "<text>" }.
Las marcas de tiempo son ISO‑8601 (UTC).

Endpoints

Método	Ruta	Descripción
`GET`	`/surveys`	Lista tus encuestas.
`POST`	`/surveys`	Crea una encuesta.
`GET`	`/surveys/{id}`	Obtén una encuesta con sus preguntas.
`PATCH`	`/surveys/{id}`	Actualiza el título, la descripción, el estado, las preguntas o la configuración.
`DELETE`	`/surveys/{id}`	Elimina una encuesta y todos sus datos.
`GET`	`/surveys/{id}/responses`	Listar respuestas (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Obtener análisis de IA en caché.
`POST`	`/surveys/{id}/analysis`	Generar análisis de IA para toda la encuesta (requiere ≥3 respuestas).

Ejemplos

Listar encuestas

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

Crear una encuesta

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":[]}'

Obtener respuestas (paginadas)

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

Límites de tasa

Las solicitudes están limitadas por cliente. Los endpoints de lectura permiten hasta 600 solicitudes/hora; las escrituras y el análisis de IA tienen límites más estrictos (la generación de IA está limitada a 30/hora). Si se supera el límite, se devuelve 429 con el rate_limited código de error — espera y vuelve a intentarlo.

Códigos de estado

200 / 201 — éxito.
400 — cuerpo de solicitud o parámetros inválidos.
401 — clave API ausente o inválida.
403 — plan de cuenta inactivo.
404 — recurso no encontrado.
422 — datos insuficientes (por ejemplo, menos de 3 respuestas para el análisis).
429 — límite de tasa excedido.
502 — proveedor de IA temporalmente no disponible.