Documentation de l’API REST

Authentification

Créez une clé API dans Paramètres (jusqu’à 3 clés actives). La clé en clair n’est affichée qu’une seule fois — conservez-la en sécurité. Envoyez-la à chaque requête comme jeton Bearer :

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Les requêtes sans clé valide et active reçoivent 401 Unauthorized. Si le forfait du compte est inactif, les endpoints retournent 403 Forbidden. Les clés peuvent être renouvelée (invalide instantanément l’ancien secret) ou supprimées à tout moment depuis les paramètres.

Conventions

Les requêtes et réponses standard utilisent JSON ; les exports fournissent des fichiers CSV, JSON ou PDF téléchargeables.
Les réponses réussies encapsulent la charge utile dans un data champ.
Les erreurs utilisent l’enveloppe { "error": "<code>", "message": "<text>" }.
Les horodatages sont au format ISO‑8601 (UTC).

Endpoints

Méthode	Chemin	Description
`GET`	`/surveys`	Listez vos enquêtes.
`POST`	`/surveys`	Créer une enquête.
`GET`	`/surveys/{id}`	Obtenez une enquête avec ses questions.
`PATCH`	`/surveys/{id}`	Modifiez le titre, la description, le statut, les questions ou les paramètres.
`DELETE`	`/surveys/{id}`	Supprimez une enquête et toutes ses données.
`GET`	`/surveys/{id}/responses`	Lister les réponses (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Obtenir l’analyse IA mise en cache.
`POST`	`/surveys/{id}/analysis`	Générer une analyse IA globale de l’enquête (nécessite ≥3 réponses).

Référence d'intégration avancée

Le catalogue ci-dessous est généré à partir de l’implémentation active. Les paramètres de requête sont utilisés pour les requêtes GET ; les autres opérations acceptent un objet JSON. Les identifiants de chemin sont fournis dans l’URL.

Consultez /api/v1/capabilities pour les schémas lisibles par machine. MCP create_survey et update_survey encapsulent les champs du sondage dans le payload ; les créations et mises à jour REST acceptent ces champs directement.

Les enquêtes acceptent jusqu’à 50 questions et 20 pages. Fournissez pages, questions, paramètres, opensAt et closesAt dans les requêtes de création ou de mise à jour. Les horodatages de planification nécessitent un fuseau horaire explicite. La publication exige au moins une question.

Les opérations IA peuvent renvoyer HTTP 202 avec jobId ; interrogez /api/v1/ai/jobs/{job_id}. Consultez /api/v1/ai/credits avant les opérations payantes. L’analyse terminée est réutilisée tant que le nombre de réponses ne change pas ; changer la langue ne déclenche pas de régénération.

Les exports de réponses CSV contiennent jusqu’à 5000 réponses complètes ; utilisez l’offset pour les pages supplémentaires. Les rapports PDF incluent les insights existants sans générer d’analyse IA payante. Les réponses partielles ont un endpoint séparé.

Pour collecter des réponses externes, demandez l’aperçu du sondage avec respondent_id et réutilisez cet identifiant lors de la soumission des réponses associées à l’ID de chaque question. Cela garantit la cohérence des variantes A/B. Ne placez jamais une clé API personnelle dans un client navigateur public.

GET /capabilities

Lire les opérations disponibles, les schémas, les permissions et les limites.

Autorisations requises: read

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

POST /surveys/{survey_id}/duplicate

Dupliquez un sondage en tant que nouveau brouillon sans réponses.

Autorisations requises: 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

Publiez, fermez ou repassez un sondage en mode brouillon.

Autorisations requises: 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

Listez les modèles de sondage localisés.

Autorisations requises: read

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

GET /templates/{template_id}

Consultez un modèle localisé avec ses questions et son thème.

Autorisations requises: 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

Créez un sondage localisé à partir d’un modèle sans crédits AI.

Autorisations requises: 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

Listez tous les types de questions pris en charge et les champs de configuration spécifiques.

Autorisations requises: read

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

POST /surveys/{survey_id}/questions

Ajoutez une question à un sondage.

Autorisations requises: 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}

Modifiez une question tout en conservant son identité.

Autorisations requises: 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}

Supprimez une question et réparez les références de logique.

Autorisations requises: 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

Réorganisez toutes les questions en conservant l’ordre principal par page.

Autorisations requises: 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

Obtenez les questions A/B résolues sans enregistrer de vue. Utilisez respondent_id pour associer les soumissions JSON suivantes.

Autorisations requises: 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

Générer des questions à partir d'une idée ou modifier progressivement des questions existantes. Coûte un crédit ; peut retourner un job.

Autorisations requises: 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}

Consulter le statut et le résultat d'un job AI appartenant à ce compte.

Autorisations requises: 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

Analyser une question à réponse libre. Les résultats en cache sont gratuits ; une analyse fraîche coûte un crédit.

Autorisations requises: 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

Lire les crédits AI disponibles, l'allocation, la consommation et les coûts des opérations.

Autorisations requises: read

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

GET /ai-panel/personas

Afficher les personas dans un panel personnel ou organisationnel, éventuellement limité à un pool.

Autorisations requises: 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}

Lire une persona synthétique.

Autorisations requises: 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

Créer une persona manuellement sans consommer de crédits AI.

Autorisations requises: 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}

Modifier les attributs d'une persona et remplacer les adhésions aux pools si fourni.

Autorisations requises: 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}

Supprimer une persona du panel.

Autorisations requises: 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

Afficher les pools nommés et le nombre de personas dans chacun.

Autorisations requises: read

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

GET /ai-panel/pools/{pool_id}

Lire un pool nommé et ses personas.

Autorisations requises: 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

Créer un pool de personas nommé.

Autorisations requises: 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}

Renommer un pool ou modifier sa description.

Autorisations requises: 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}

Supprimer un pool et détacher ses membres sans supprimer les personas.

Autorisations requises: 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

Ajouter ou retirer des personas d'un pool en masse.

Autorisations requises: 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

Importer des personas depuis un JSON. Les métadonnées du pool sont ignorées ; les personas importés ne sont pas assignés.

Autorisations requises: 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

Exporter des personas ou un pool en JSON ou CSV.

Autorisations requises: 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

Générer des personas avec AI. Coûte cinq crédits par persona, avec remboursement en cas de résultat manquant.

Autorisations requises: 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

Estimer les crédits nécessaires pour administrer un sondage à un pool nommé.

Autorisations requises: 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

Administrer un sondage à un pool nommé. Coûte trois crédits par persona ; peut retourner un job.

Autorisations requises: 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

Lire les statistiques par question, les répartitions A/B, les vues, les comptes AI-panel et l'analyse des abandons.

Autorisations requises: 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

Consultez les réponses en cours, séparément des soumissions complètes.

Autorisations requises: 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

Téléchargez les réponses complètes au format CSV (jusqu'à 5000 par page) ou un rapport PDF des résultats.

Autorisations requises: 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

Importez une image PNG, JPEG, GIF ou WebP encodée en base64 (maximum 5 Mo) pour le thème du sondage.

Autorisations requises: 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

Soumettez une réponse complète pour un répondant externe ; applique les règles de publication, de calendrier, de logique et de doublons.

Autorisations requises: 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

Enregistrez automatiquement la réponse partielle d’un répondant externe lorsque la collecte est activée.

Autorisations requises: 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

Lire le profil, la langue, le domaine, le forfait et l'accès à l'organisation.

Autorisations requises: read

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

PATCH /account

Modifier le nom affiché, la langue du service ou le domaine personnalisé. N'affecte pas l'email, les identifiants ou la facturation.

Autorisations requises: 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

Consulter l'organisation, les licences disponibles et les crédits AI partagés.

Autorisations requises: read

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

GET /organization/members

Afficher les membres, rôles, licences et la consommation AI de l'organisation. Administrateurs uniquement.

Autorisations requises: read

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

POST /organization/members

Ajouter un compte Votira existant à l'organisation. Administrateurs uniquement.

Autorisations requises: 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}

Modifier le rôle ou la licence attribuée d'un membre. Administrateurs uniquement ; le propriétaire est protégé.

Autorisations requises: 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}

Retirer un membre sans supprimer son compte. Administrateurs uniquement.

Autorisations requises: 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

Afficher les invitations de l'organisation sans révéler les jetons d'invitation. Administrateurs uniquement.

Autorisations requises: read

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

POST /organization/invites

Créer une invitation et retourner son URL de partage. Administrateurs uniquement.

Autorisations requises: 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}

Révoquer une invitation en attente dans l'organisation. Administrateurs uniquement.

Autorisations requises: 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

Rechercher dans le journal d'audit de l'organisation. Administrateurs entreprise uniquement.

Autorisations requises: 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

Exporter jusqu'à 5000 entrées d'audit en CSV. Administrateurs entreprise uniquement.

Autorisations requises: 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

Afficher les factures personnelles payées et, pour les administrateurs, celles de l'organisation.

Autorisations requises: 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

Télécharger un PDF de facture payée après vérification du titulaire de la facturation.

Autorisations requises: read

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

GET /support

Afficher les tickets de support, rapports de bugs et demandes de fonctionnalités du compte.

Autorisations requises: 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}

Lire une demande de support et les réponses de l'équipe, limité à son propriétaire.

Autorisations requises: read

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

POST /support

Ouvrir un ticket de support, un rapport de bug ou une demande de fonctionnalité.

Autorisations requises: 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"
}

Exemples

Lister les enquêtes

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

Créer une enquête

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

Récupérer les réponses (paginées)

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

Limites de taux

Les requêtes sont limitées par client. Les points de terminaison de lecture autorisent jusqu’à 600 requêtes/heure ; les écritures et l’analyse IA sont plus strictement limitées (la génération IA est plafonnée à 30/heure). Dépasser une limite renvoie 429 avec le rate_limited code d’erreur — attendez et réessayez.

Codes de statut

200 / 201 — succès.
202 — Tâche IA acceptée ; vérifiez son statut.
402 — Plus de crédits IA disponibles.
409 — L'opération est en conflit avec l'état actuel de la ressource.
400 — corps de requête ou paramètres invalides.
401 — clé API manquante ou invalide.
403 — forfait du compte inactif.
404 — ressource non trouvée.
422 — pas assez de données (par exemple moins de 3 réponses pour l’analyse).
429 — limite de taux dépassée.
502 — fournisseur IA temporairement indisponible.

Votira REST API

Authentification

Conventions

Endpoints

Référence d'intégration avancée

Exemples

Limites de taux

Codes de statut

Arrêtez de deviner. Commencez à valider.