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

Le richieste e le risposte standard usano JSON; le esportazioni restituiscono file CSV, JSON o PDF scaricabili.
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).

Riferimento esteso per l'integrazione

Il catalogo qui sotto è generato dall'implementazione attiva. I parametri di query sono usati per le richieste GET; le altre operazioni accettano un oggetto JSON. Gli identificatori di percorso sono forniti nell'URL.

Consulta /api/v1/capabilities per schemi leggibili dalle macchine. MCP create_survey e update_survey racchiudono i campi del sondaggio nel payload; la creazione e gli aggiornamenti REST accettano direttamente quei campi.

I sondaggi supportano fino a 50 domande e 20 pagine. Fornisci pagine, domande, impostazioni, opensAt e closesAt nelle richieste di creazione o aggiornamento. I timestamp di pianificazione richiedono un fuso orario esplicito. La pubblicazione richiede almeno una domanda.

Le operazioni AI possono restituire HTTP 202 con jobId; verifica /api/v1/ai/jobs/{job_id}. Consulta /api/v1/ai/credits prima delle operazioni a pagamento. L’analisi completata viene riutilizzata finché il numero di risposte non cambia; cambiare lingua non genera una nuova analisi.

Le esportazioni CSV includono fino a 5000 risposte completate; usa l’offset per pagine aggiuntive. I report PDF includono gli insight esistenti senza generare analisi AI a pagamento. Le risposte parziali hanno un endpoint dedicato.

Per la raccolta di risposte esterne, richiedi l'anteprima del sondaggio con respondent_id e riutilizza quell'identificatore quando invii le risposte associate all'ID della domanda. Questo mantiene coerenti le varianti A/B. Non inserire mai una chiave API personale in un client browser pubblico.

GET /capabilities

Visualizza operazioni disponibili, schemi, permessi e limiti.

Permessi richiesti: read

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

POST /surveys/{survey_id}/duplicate

Duplica un sondaggio come nuovo bozza senza risposte.

Permessi richiesti: 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

Pubblica, chiudi o riporta un sondaggio a bozza.

Permessi richiesti: 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

Elenca i modelli di sondaggio localizzati.

Permessi richiesti: read

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

GET /templates/{template_id}

Visualizza un modello localizzato con domande e tema.

Permessi richiesti: 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 un sondaggio localizzato da un modello senza crediti AI.

Permessi richiesti: 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

Elenca tutti i tipi di domanda supportati e i campi di configurazione specifici per tipo.

Permessi richiesti: read

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

POST /surveys/{survey_id}/questions

Aggiungi una domanda al sondaggio.

Permessi richiesti: 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}

Aggiorna una domanda mantenendo la sua identità.

Permessi richiesti: 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 domanda e ripara i riferimenti di ramificazione.

Permessi richiesti: 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

Riordina tutte le domande, mantenendo l'ordine principale delle pagine.

Permessi richiesti: 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

Ottieni domande A/B risolte senza registrare una visualizzazione. Usa respondent_id per abbinare invii JSON successivi.

Permessi richiesti: 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

Genera domande da un'idea o modifica domande esistenti in modo incrementale. Costa un credito; può restituire un job.

Permessi richiesti: 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}

Visualizza stato e risultato di un job AI di proprietà di questo account.

Permessi richiesti: 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

Analizza una domanda a testo libero. I risultati memorizzati sono gratuiti; l'analisi nuova costa un credito.

Permessi richiesti: 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

Visualizza crediti AI disponibili, limiti, consumo e costi delle operazioni.

Permessi richiesti: read

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

GET /ai-panel/personas

Elenca persone in un pannello personale o organizzativo, eventualmente limitate a un pool.

Permessi richiesti: 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}

Visualizza una persona sintetica.

Permessi richiesti: 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

Crea manualmente una persona senza consumare crediti AI.

Permessi richiesti: 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}

Modifica attributi della persona e sostituisci le appartenenze ai pool se fornito.

Permessi richiesti: 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}

Elimina una persona dal pannello.

Permessi richiesti: 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

Elenca pool nominati e il conteggio delle persone.

Permessi richiesti: read

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

GET /ai-panel/pools/{pool_id}

Visualizza un pool nominato e le sue persone.

Permessi richiesti: 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

Crea un pool di persone nominato.

Permessi richiesti: 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}

Rinomina un pool o aggiorna la sua descrizione.

Permessi richiesti: 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}

Elimina un pool e scollega i suoi membri senza eliminare le persone.

Permessi richiesti: 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

Aggiungi o rimuovi persone da un pool in modo massivo.

Permessi richiesti: 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

Importa persone da JSON. I metadati del pool vengono ignorati; le persone importate non sono assegnate.

Permessi richiesti: 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

Esporta persone o un pool come JSON o CSV.

Permessi richiesti: 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

Genera persone con AI. Costa cinque crediti per persona, con rimborsi per risultati mancanti.

Permessi richiesti: 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

Stima i crediti necessari per somministrare un sondaggio a un pool nominato.

Permessi richiesti: 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

Somministra un sondaggio a un pool nominato. Costa tre crediti per persona; può restituire un job.

Permessi richiesti: 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

Visualizza statistiche per domanda, suddivisioni A/B, visualizzazioni, conteggi AI-panel e analisi drop-off.

Permessi richiesti: 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

Visualizza le risposte in corso, separate da quelle completate.

Permessi richiesti: 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

Scarica le risposte completate in formato CSV (fino a 5000 per pagina) o un report dei risultati in PDF.

Permessi richiesti: 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

Carica un'immagine PNG, JPEG, GIF o WebP codificata in base64 (massimo 5 MB) per il tema del sondaggio.

Permessi richiesti: 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

Invia una risposta completata per un rispondente esterno; applica regole di pubblicazione, programmazione, ramificazione e duplicati.

Permessi richiesti: 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

Salvataggio automatico della risposta parziale di un rispondente esterno quando la raccolta è abilitata.

Permessi richiesti: 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

Visualizza profilo, lingua, dominio, piano e accesso all'organizzazione.

Permessi richiesti: read

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

PATCH /account

Aggiorna nome visualizzato, lingua del servizio o dominio personalizzato. Non modifica email, credenziali o fatturazione.

Permessi richiesti: 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

Visualizza l'organizzazione, licenze disponibili e crediti AI condivisi.

Permessi richiesti: read

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

GET /organization/members

Elenca membri dell'organizzazione, ruoli, licenze e consumo AI. Solo amministratori.

Permessi richiesti: read

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

POST /organization/members

Aggiungi un account Votira esistente all'organizzazione. Solo amministratori.

Permessi richiesti: 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}

Aggiorna il ruolo o la licenza assegnata a un membro. Solo amministratori; il proprietario è protetto.

Permessi richiesti: 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}

Rimuovi un membro senza eliminare il suo account. Solo amministratori.

Permessi richiesti: 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

Elenca inviti dell'organizzazione senza mostrare i token di invito. Solo amministratori.

Permessi richiesti: read

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

POST /organization/invites

Crea un invito e restituisci il suo URL di condivisione. Solo amministratori.

Permessi richiesti: 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}

Revoca un invito pendente dell'organizzazione. Solo amministratori.

Permessi richiesti: 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

Cerca nel registro delle attività dell'organizzazione. Solo amministratori Enterprise.

Permessi richiesti: 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

Esporta fino a 5000 voci di audit come CSV. Solo amministratori Enterprise.

Permessi richiesti: 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

Elenca fatture personali pagate e, per gli amministratori, fatture dell'organizzazione.

Permessi richiesti: 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

Scarica un PDF di fattura pagata dopo aver verificato la proprietà della fatturazione dell'account.

Permessi richiesti: read

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

GET /support

Elenca ticket di supporto, segnalazioni di bug e richieste di funzionalità dell'account.

Permessi richiesti: 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}

Visualizza una richiesta di supporto e le risposte del team, limitate al suo proprietario.

Permessi richiesti: read

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

POST /support

Apri un ticket di supporto, segnala un bug o richiedi una funzionalità.

Permessi richiesti: 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"
}

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.
202 — Job AI accettato; verifica lo stato.
402 — Nessun credito AI disponibile.
409 — L’operazione è in conflitto con lo stato attuale della risorsa.
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.

Votira REST API

Autenticazione

Convenzioni

Endpoint

Riferimento esteso per l'integrazione

Esempi

Limiti di frequenza

Codici di stato

Basta ipotesi. Inizia a validare.