Documentazione REST API

Autenticazione

Crea una chiave API in Impostazioni (fino a 3 chiavi attive). La chiave in chiaro viene mostrata solo una volta: conservala in modo sicuro. Invia la chiave in ogni richiesta come Bearer token:

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Le richieste senza una chiave valida e attiva ricevono 401 Unauthorized. Se il piano dell’account è inattivo, gli endpoint restituiscono 403 Forbidden. Le chiavi possono essere ruotata (invalida istantaneamente il vecchio segreto) oppure eliminate in qualsiasi momento dalle Impostazioni.

Convenzioni

Tutte le richieste e risposte usano application/json.
Le risposte con successo racchiudono il payload in un data campo.
Gli errori usano l’envelope { "error": "<code>", "message": "<text>" }.
I timestamp sono in formato ISO‑8601 (UTC).

Endpoint

Metodo	Percorso	Descrizione
`GET`	`/surveys`	Elenca i tuoi sondaggi.
`POST`	`/surveys`	Crea un sondaggio.
`GET`	`/surveys/{id}`	Ottieni un sondaggio con le sue domande.
`PATCH`	`/surveys/{id}`	Aggiorna titolo, descrizione, stato, domande o impostazioni.
`DELETE`	`/surveys/{id}`	Elimina un sondaggio e tutti i suoi dati.
`GET`	`/surveys/{id}/responses`	Elenca risposte (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Ottieni analisi AI memorizzata.
`POST`	`/surveys/{id}/analysis`	Genera analisi AI per l’intero sondaggio (richiede almeno 3 risposte).

Esempi

Elenca sondaggi

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

Crea un sondaggio

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

Recupera risposte (paginato)

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

Limiti di frequenza

Le richieste sono limitate per client. Gli endpoint di lettura consentono fino a 600 richieste/ora; scritture e analisi AI sono più limitate (la generazione AI è limitata a 30/ora). Se superi il limite viene restituito 429 con il rate_limited codice di errore — attendi e riprova.

Codici di stato

200 / 201 — successo.
400 — corpo della richiesta o parametri non validi.
401 — API key mancante o non valida.
403 — piano account inattivo.
404 — risorsa non trovata.
422 — dati insufficienti (es. meno di 3 risposte per l’analisi).
429 — limite di frequenza superato.
502 — Fornitore AI temporaneamente non disponibile.