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

Las solicitudes y respuestas estándar usan JSON; las exportaciones devuelven archivos CSV, JSON o PDF descargables.
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).

Referencia ampliada de integración

El catálogo siguiente se genera a partir de la implementación activa. Los parámetros de consulta se usan para solicitudes GET; otras operaciones aceptan un objeto JSON. Los identificadores de ruta se incluyen en la URL.

Consulta /api/v1/capabilities para esquemas legibles por máquina. MCP create_survey y update_survey envuelven los campos de encuesta en el payload; la creación y actualización por REST aceptan esos campos directamente.

Las encuestas admiten hasta 50 preguntas y 20 páginas. Proporciona páginas, preguntas, ajustes, opensAt y closesAt en las solicitudes de creación o actualización. Las marcas de tiempo de programación requieren una zona horaria explícita. Publicar requiere al menos una pregunta.

Las operaciones de IA pueden devolver HTTP 202 con jobId; consulta /api/v1/ai/jobs/{job_id}. Lee /api/v1/ai/credits antes de operaciones de pago. El análisis completado se reutiliza hasta que cambie el número de respuestas; cambiar el idioma no genera un nuevo análisis.

Las exportaciones de respuestas en CSV incluyen hasta 5000 respuestas completas; usa offset para páginas adicionales. Los informes PDF incluyen los insights existentes sin generar análisis de IA de pago. Las respuestas parciales tienen un endpoint separado.

Para la recogida externa de respuestas, solicita la vista previa de la encuesta con respondent_id y reutiliza ese identificador al enviar respuestas asociadas por ID de pregunta. Esto mantiene la coherencia de las variantes A/B. Nunca coloques una clave API personal en un cliente de navegador público.

GET /capabilities

Consultar operaciones disponibles, esquemas, permisos y límites.

Permisos requeridos: read

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

POST /surveys/{survey_id}/duplicate

Duplica una encuesta como un nuevo borrador sin respuestas.

Permisos requeridos: 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

Publica, cierra o devuelve una encuesta a borrador.

Permisos requeridos: 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

Lista plantillas de encuestas localizadas.

Permisos requeridos: read

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

GET /templates/{template_id}

Lee una plantilla localizada con preguntas y tema.

Permisos requeridos: 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

Crea una encuesta localizada a partir de una plantilla sin créditos de IA.

Permisos requeridos: 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

Lista todos los tipos de preguntas compatibles y los campos de configuración específicos de cada tipo.

Permisos requeridos: read

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

POST /surveys/{survey_id}/questions

Añade una pregunta a una encuesta.

Permisos requeridos: 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}

Actualiza una pregunta manteniendo su identidad.

Permisos requeridos: 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}

Elimina una pregunta y repara las referencias de ramificación.

Permisos requeridos: 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

Reordena todas las preguntas, manteniendo el orden principal por página.

Permisos requeridos: 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

Obtén preguntas A/B resueltas sin registrar una visualización. Usa respondent_id para asociar envíos JSON posteriores.

Permisos requeridos: 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

Generar preguntas a partir de una idea o editar preguntas existentes de forma incremental. Cuesta un crédito; puede devolver un trabajo.

Permisos requeridos: 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}

Consultar el estado y resultado de un trabajo de IA propiedad de esta cuenta.

Permisos requeridos: 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

Analizar una pregunta de texto libre. Los resultados en caché son gratuitos; el análisis nuevo cuesta un crédito.

Permisos requeridos: 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

Consultar créditos de IA disponibles, asignación, consumo y costes de operación.

Permisos requeridos: read

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

GET /ai-panel/personas

Listar personas en un panel personal u organizativo, opcionalmente restringido a un grupo.

Permisos requeridos: 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}

Consultar una persona sintética.

Permisos requeridos: 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

Crear una persona manualmente sin consumir créditos de IA.

Permisos requeridos: 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 de una persona y reemplazar membresías de grupo si se indica.

Permisos requeridos: 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 una persona del panel.

Permisos requeridos: 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 con nombre y el número de personas en cada uno.

Permisos requeridos: read

{
  "additionalProperties": false,
  "properties": {
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

GET /ai-panel/pools/{pool_id}

Consultar un grupo por nombre y sus personas.

Permisos requeridos: 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

Crear un grupo de personas con nombre.

Permisos requeridos: 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}

Renombrar un grupo o actualizar su descripción.

Permisos requeridos: 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 un grupo y desvincular sus miembros sin borrar personas.

Permisos requeridos: 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

Añadir o quitar personas de un grupo de forma masiva.

Permisos requeridos: 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 desde JSON. Se ignora la información del grupo; las personas importadas quedan sin asignar.

Permisos requeridos: 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 o un grupo como JSON o CSV.

Permisos requeridos: 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

Generar personas con IA. Cuesta cinco créditos por persona, con reembolso si faltan resultados.

Permisos requeridos: 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 los créditos necesarios para administrar una encuesta a un grupo con nombre.

Permisos requeridos: 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 una encuesta a un grupo con nombre. Cuesta tres créditos por persona; puede devolver un trabajo.

Permisos requeridos: 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

Consultar estadísticas por pregunta, desglose A/B, visualizaciones, recuentos en panel de IA y análisis de abandono.

Permisos requeridos: 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

Lee respuestas en curso, por separado de los envíos completados.

Permisos requeridos: 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

Descarga las respuestas completadas en formato CSV (hasta 5000 por página) o un informe de resultados en PDF.

Permisos requeridos: 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

Sube una imagen en formato PNG, JPEG, GIF o WebP codificada en base64 (máximo 5 MB) para el tema de la encuesta.

Permisos requeridos: 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

Envía una respuesta completada para un participante externo; se aplican las reglas de publicación, programación, ramificación y duplicados.

Permisos requeridos: 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

Guarda automáticamente una respuesta parcial de un participante externo cuando la recopilación está habilitada.

Permisos requeridos: 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

Leer perfil, idioma, dominio, plan y acceso a la organización.

Permisos requeridos: read

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

PATCH /account

Actualizar nombre visible, idioma del servicio o dominio personalizado. No modifica el correo, credenciales ni facturación.

Permisos requeridos: 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

Consultar la organización, licencias disponibles y créditos de IA compartidos.

Permisos requeridos: read

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

GET /organization/members

Listar miembros, roles, licencias y consumo de IA de la organización. Solo administradores.

Permisos requeridos: read

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

POST /organization/members

Añadir una cuenta de Votira existente a la organización. Solo administradores.

Permisos requeridos: 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}

Actualizar el rol o la licencia asignada de un miembro. Solo administradores; el propietario está protegido.

Permisos requeridos: 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}

Eliminar un miembro sin borrar su cuenta. Solo administradores.

Permisos requeridos: 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 invitaciones de la organización sin mostrar los tokens de invitación. Solo administradores.

Permisos requeridos: read

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

POST /organization/invites

Crear una invitación y devolver su URL para compartir. Solo administradores.

Permisos requeridos: 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}

Revocar una invitación pendiente de la organización. Solo administradores.

Permisos requeridos: 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

Buscar en el registro de auditoría de la organización. Solo administradores Enterprise.

Permisos requeridos: 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 hasta 5000 registros de auditoría como CSV. Solo administradores Enterprise.

Permisos requeridos: 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 facturas personales pagadas y, para administradores, facturas de la organización.

Permisos requeridos: 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

Descargar un PDF de factura pagada tras verificar la titularidad de la facturación.

Permisos requeridos: read

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

GET /support

Listar los tickets de soporte, informes de errores y solicitudes de funciones de la cuenta.

Permisos requeridos: 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}

Leer una solicitud de soporte y las respuestas del equipo, solo para su propietario.

Permisos requeridos: 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 un ticket de soporte, informe de error o solicitud de función.

Permisos requeridos: 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"
}

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.
202 — Trabajo de IA aceptado; consulta su estado.
402 — No quedan créditos de IA.
409 — La operación entra en conflicto con el estado actual del recurso.
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.

Votira REST API

Autenticación

Convenciones

Endpoints

Referencia ampliada de integración

Ejemplos

Límites de tasa

Códigos de estado

Deja de adivinar. Empieza a validar.