Aller au contenu
Base de connaissances

API REST

Askalot propose une API REST qui donne accès par programmation à toutes les fonctionnalités de la plateforme. Elle vous permet d’automatiser vos processus d’enquête, de vous intégrer à des systèmes externes et de construire vos propres applications au-dessus de la plateforme Askalot.

https://portor.<tenant>.askalot.io/api/v1

Remplacez <tenant> par le nom de tenant de votre organisation (par exemple portor.acme.askalot.io).

Toutes les requêtes à l’API doivent être authentifiées au moyen d’un jeton API personnel.

Générer un jeton :

  1. Connectez-vous à https://roundtable.<tenant>.askalot.io
  2. Ouvrez « Paramètres du profil »
  3. Faites défiler jusqu’à la section « Jetons API »
  4. Cliquez sur « Générer un nouveau jeton »
  5. Copiez le jeton (il n’est affiché qu’une seule fois)

Utiliser votre jeton :

Placez votre jeton dans l’en-tête X-Api-Token :

Fenêtre de terminal
curl -H "X-Api-Token: your_token_here" \
https://portor.<tenant>.askalot.io/api/v1/projects

Propriétés du jeton :

  • Format : les jetons commencent par aslat_ (aslat_<32 characters>) ; ce préfixe permet aux outils de détection de secrets de repérer un commit accidentel. Seul le préfixe est conservé côté serveur à des fins d’identification : le jeton complet est affiché une fois à la création, puis plus jamais.
  • En-tête : envoyez-le dans l’en-tête X-Api-Token. C’est la voie d’authentification de REST ; l’en-tête Authorization: Bearer de Portor est réservé aux jetons d’accès OAuth (ceux que porte une session MCP, que REST accepte aussi), et non aux jetons API.
  • Portée : il authentifie uniquement l’API REST et n’est pas accepté par l’interface MCP. Un jeton appartient à l’organisation dans laquelle vous travailliez au moment de sa génération : chaque requête qu’il effectue agit dans cette organisation, avec les rôles que vous y détenez ; un rôle détenu dans une autre organisation ne s’applique pas. Pour travailler dans une autre organisation via REST, basculez vers celle-ci dans le navigateur et générez-y un jeton. Si un administrateur vous retire de cette organisation, ses jetons sont révoqués en même temps que votre adhésion.
  • Révocation : révoquez un jeton à tout moment depuis « Paramètres du profil » ; la révocation prend effet immédiatement.

Vous choisissez une date d’expiration lors de la création d’un jeton : la liste déroulante de « Paramètres du profil » propose 30 jours, 90 jours (par défaut) ou 1 an. L’expiration est obligatoire ; il n’existe pas d’option « sans expiration » pour les nouveaux jetons (seuls d’anciens jetons, conservés à titre dérogatoire, peuvent en être dépourvus).

  • La page « Paramètres du profil » affiche la date d’expiration de chaque jeton et le nombre de jours restants, et signale qu’un jeton doit être renouvelé dès qu’il se trouve à moins de 14 jours de son expiration.
  • Pour renouveler : créez un jeton de remplacement, mettez à jour votre intégration pour qu’elle l’utilise, puis révoquez l’ancien. Les jetons ne se renouvellent pas automatiquement : un jeton expiré renvoie 401 et doit être remplacé.

Explorez l’API de manière interactive avec Swagger UI à l’adresse :

https://portor.<tenant>.askalot.io/api/v1/docs

La documentation interactive vous permet de :

  • Parcourir tous les points de terminaison disponibles
  • Consulter les schémas des requêtes et des réponses
  • Tester des appels à l’API directement dans votre navigateur

Les projets sont les conteneurs de premier niveau qui organisent vos travaux de recherche par enquête.

Méthode Point de terminaison Description
GET /api/v1/projects Liste tous les projets
POST /api/v1/projects Crée un nouveau projet
GET /api/v1/projects/{id} Renvoie un projet par son identifiant
PUT /api/v1/projects/{id} Met à jour un projet
DELETE /api/v1/projects/{id} Supprime un projet
POST /api/v1/projects/{id}/owners Ajoute des propriétaires au projet
DELETE /api/v1/projects/{id}/owners Retire des propriétaires du projet

Exemple : créer un projet

Fenêtre de terminal
curl -X POST https://portor.<tenant>.askalot.io/api/v1/projects \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Satisfaction Study",
"description": "Q1 2026 customer feedback survey"
}'

Réponse :

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Customer Satisfaction Study",
"description": "Q1 2026 customer feedback survey",
"created_at": "2026-01-02T10:30:00Z",
"questionnaire_ids": [],
"campaign_ids": []
}

Les questionnaires définissent la structure de l’enquête en QML (Questionnaire Markup Language).

Méthode Point de terminaison Description
GET /api/v1/questionnaires Liste tous les questionnaires
POST /api/v1/questionnaires Crée un nouveau questionnaire
GET /api/v1/questionnaires/{id} Renvoie un questionnaire par son identifiant
PUT /api/v1/questionnaires/{id} Met à jour un questionnaire
DELETE /api/v1/questionnaires/{id} Supprime un questionnaire
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations Liste les traductions d’une version, par langue (complète, clés non traduites, figée, modifiée à la main)
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Renvoie la traduction dans une langue avec ses textes source
PUT /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Enregistre du texte traduit (texts, base_updated_at) ; partiel, fusionné avec ce qui est stocké
DELETE /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Supprime la traduction dans une langue (refusé une fois figée)

Paramètres de requête :

  • project_id : filtre par projet
  • status : filtre par statut (draft, active, paused, completed)

Les campagnes relient les questionnaires aux répondants pour la collecte des données.

Méthode Point de terminaison Description
GET /api/v1/campaigns Liste toutes les campagnes
POST /api/v1/campaigns Crée une nouvelle campagne
GET /api/v1/campaigns/{id} Renvoie une campagne par son identifiant
PUT /api/v1/campaigns/{id} Met à jour une campagne
DELETE /api/v1/campaigns/{id} Supprime une campagne
PUT /api/v1/campaigns/{id}/pool Affecte un vivier de répondants à la campagne
GET /api/v1/campaigns/{id}/pool Renvoie le vivier affecté à la campagne
PUT /api/v1/campaigns/{id}/questionnaire Change le questionnaire de la campagne
POST /api/v1/campaigns/{id}/interviewers Ajoute des enquêteurs à la campagne
DELETE /api/v1/campaigns/{id}/interviewers Retire des enquêteurs de la campagne

Paramètres de requête :

  • project_id : filtre par projet
  • questionnaire_id : filtre par questionnaire
  • status : filtre par statut
  • expand=true : inclut les objets liés (projet, questionnaire, répondants)

Créer une campagne : POST /api/v1/campaigns exige name, project_id, questionnaire_id et offers_ai_channel. offers_ai_channel (booléen) indique si les répondants peuvent aussi répondre à l’enquête dans leur propre assistant IA. Il n’a pas de valeur par défaut, et une requête qui l’omet est refusée. Lorsqu’il vaut true, intro_text et consent_text sont également obligatoires. Voir Auto-entretien assisté par l’IA.

Modes de campagne :

Askalot prend en charge deux modes de campagne :

  • Mode direct : les répondants remplissent les enquêtes de manière autonome grâce à des liens uniques
  • Mode avec enquêteur : des enquêteurs administrent les enquêtes aux répondants par téléphone ou en face à face

Le mode est déterminé automatiquement selon que des enquêteurs sont affectés ou non à la campagne.

Chaque enquête enregistre aussi son propre mode (direct, ai_assisted ou field_interview) dans son champ mode. Une enquête est ai_assisted lorsque la campagne propose l’assistant IA et que le répondant y a donné son consentement avant de répondre.

Les répondants sont les cibles de l’enquête, c’est-à-dire les personnes interrogées.

Méthode Point de terminaison Description
GET /api/v1/respondents Liste tous les répondants
POST /api/v1/respondents Crée un nouveau répondant
GET /api/v1/respondents/{id} Renvoie un répondant par son identifiant
PUT /api/v1/respondents/{id} Met à jour un répondant
DELETE /api/v1/respondents/{id} Supprime un répondant

Paramètres de requête :

  • source_system : filtre par source (par exemple crm, panel_provider)
  • campaign_id : filtre par campagne

Remarque : les enquêteurs sont des utilisateurs ayant le rôle interviewer. Ils se gèrent via le point de terminaison /api/v1/users.

Exemple : importer un répondant

Fenêtre de terminal
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "[email protected]",
"age": 35,
"gender": "female",
"location": "New York",
"external_id": "CRM-12345",
"source_system": "salesforce",
"custom_attributes": {"state": "NY", "zip_code": "10001"}
}'

Champs démographiques :

Les répondants peuvent porter des données démographiques utilisées pour le ciblage et l’analyse :

  • age : âge du répondant
  • gender : identité de genre
  • location : localisation géographique (texte libre, généralement "City, Country")
  • external_id : l’identifiant dans votre système
  • source_system : source des données du répondant
  • preferred_language : langue préférée facultative (en, es, fr, de, hu), utilisée pour l’invitation et comme langue présélectionnée de l’enquête lorsque la campagne la propose

Une géographie plus fine que location (rue, ville, région, code postal, pays en valeurs distinctes) se place dans custom_attributes, et peut être désignée par custom_attributes.<key> partout où l’on peut nommer un attribut de répondant (facteurs d’échantillonnage, correspondances d’entrées externes). Une cible de calage nomme la colonne du jeu de données dans laquelle l’attribut a été extrait, _custom_<key>. Les clés supplémentaires de premier niveau sont ignorées plutôt que stockées : un export CRM qui envoie city comme champ à part perd donc cette valeur sans avertissement.

Les enquêtes suivent chaque session d’enquête et ses réponses.

Méthode Point de terminaison Description
GET /api/v1/surveys Liste toutes les enquêtes
POST /api/v1/surveys Crée une nouvelle session d’enquête
GET /api/v1/surveys/{id} Renvoie une enquête par son identifiant
PUT /api/v1/surveys/{id} Met à jour le statut d’une enquête
DELETE /api/v1/surveys/{id} Supprime une enquête
GET /api/v1/surveys/{id}/current-step Question courante + options + statut (Format de présentation des enquêtes)
POST /api/v1/surveys/{id}/responses Soumet une réponse ; l’étape suivante est intégrée à la réponse
POST /api/v1/surveys/{id}/finish Termine explicitement l’enquête (idempotent)

Paramètres de requête :

  • questionnaire_id : filtre par questionnaire
  • campaign_id : filtre par campagne
  • respondent_id : filtre par répondant
  • status : filtre par statut (pending, in_progress, completed)
  • expand=true : inclut les objets liés

Les réponses relatives aux enquêtes portent status ainsi qu’un booléen dérivé en lecture seule, completed (true exactement lorsque status vaut completed). L’achèvement s’exprime en mettant à jour status : il n’existe ni entrée ni paramètre de filtre completed.

Répondre à une enquête via POST /api/v1/surveys/{id}/responses est réservé aux tests et à la simulation : pour une enquête dont l’invitation a été envoyée, la requête est refusée, si bien qu’un entretien réel sur le terrain ne peut pas être écrit par programmation. Les réponses soumises de cette façon sont enregistrées comme produites par une machine, et leurs temps de réponse sont exclus de la détection des répondants trop rapides.

Les viviers de répondants organisent les répondants en groupes réutilisables pour les campagnes.

Méthode Point de terminaison Description
GET /api/v1/respondent-pools Liste tous les viviers de répondants
POST /api/v1/respondent-pools Crée un nouveau vivier
GET /api/v1/respondent-pools/{id} Renvoie un vivier par son identifiant
DELETE /api/v1/respondent-pools/{id} Supprime un vivier
POST /api/v1/respondent-pools/{id}/respondents Ajoute des répondants au vivier
DELETE /api/v1/respondent-pools/{id}/respondents Retire des répondants du vivier
POST /api/v1/respondent-pools/generate Tire un vivier d’une stratégie d’échantillonnage (requested_size obligatoire) ; le vivier conserve ses paramètres de tirage
POST /api/v1/respondent-pools/preview Prévisualise un tirage sans créer de vivier
POST /api/v1/respondent-pools/{id}/refresh Tire à nouveau un vivier issu d’une stratégie, avec les paramètres de tirage qu’il a enregistrés

Paramètres de requête :

  • project_id : filtre par projet

Les stratégies d’échantillonnage définissent des distributions démographiques cibles pour constituer des échantillons représentatifs, ainsi que la manière d’évaluer l’adéquation à ces cibles. Une stratégie ne porte aucun paramètre de taille ni de sélection : ce sont des entrées de POST /api/v1/respondent-pools/generate, enregistrées sur le vivier qu’il crée.

Méthode Point de terminaison Description
GET /api/v1/sampling-strategies Liste toutes les stratégies
POST /api/v1/sampling-strategies Crée une nouvelle stratégie
GET /api/v1/sampling-strategies/{id} Renvoie une stratégie par son identifiant
PUT /api/v1/sampling-strategies/{id} Met à jour une stratégie
DELETE /api/v1/sampling-strategies/{id} Supprime une stratégie

Paramètres de requête :

  • project_id : filtre par projet

Exemple : créer une stratégie d’échantillonnage

Fenêtre de terminal
curl -X POST https://portor.<tenant>.askalot.io/api/v1/sampling-strategies \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Representative Sample",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"factors": [
{
"name": "Gender",
"attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}
},
{
"name": "Age Group",
"attribute_path": "age",
"factor_type": "bucketed",
"target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25}
}
]
}'

Exemple : tirer un vivier de la stratégie

Fenêtre de terminal
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondent-pools/generate \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"strategy_id": "<strategy id>",
"pool_name": "Pilot wave",
"requested_size": 100,
"oversample_factor": 1.2
}'

requested_size est obligatoire ; oversample_factor (1.0 par défaut), selection_algorithm (greedy ou random_constrained, greedy par défaut), require_email (false par défaut) et exclude_respondent_ids (aucun par défaut) sont facultatifs. Tirez un second vivier de la même stratégie, à une autre taille, chaque fois que vous en avez besoin.

Un lot associe un projet → un questionnaire → un sous-ensemble choisi de campagnes à une chaîne linéaire unique de jeux de données Bronze → Silver → Gold : c’est l’unité autour de laquelle s’organise le tableau du pipeline de Balansor.

Méthode Point de terminaison Description
GET /api/v1/bundles Liste tous les lots
POST /api/v1/bundles Crée un nouveau lot
GET /api/v1/bundles/{id} Détail d’un lot, y compris les recettes de ses étapes (cibles de calage Silver, opérations Gold)
DELETE /api/v1/bundles/{id} Supprime un lot (et sa chaîne de jeux de données)
POST /api/v1/bundles/{id}/clone Clone un lot en profondeur : les jeux de données prêts et les recettes des étapes sont repris
GET /api/v1/bundles/{id}/quality Le bilan de représentativité du lot (sélection, terrain, pondération, écart dû au terrain, réponse)
GET /api/v1/bundles/{id}/comparison Comparaison Bronze-Silver (409 conflict tant que les deux étapes ne sont pas ready)
GET /api/v1/bundles/{id}/coding État du codage des questions ouvertes : les candidats au codage que propose le jeu de données Bronze, la sélection de questions de l’analyste et, par question, les dimensions proposées avec leurs catégories et leur état de sélection (le choix des dimensions qui deviennent des colonnes reste dans l’interface de Balansor)
PUT /api/v1/bundles/{id}/coding/selection Définit les unités de texte ouvert que ce lot code : l’ensemble complet des clés d’unités, qui remplace le précédent (rôle Gestionnaire, utilisateur identifié requis)
POST /api/v1/bundles/{id}/strategy Affecte ou retire la stratégie d’échantillonnage courante du lot (rôle Gestionnaire, utilisateur identifié requis)
PUT /api/v1/bundles/{id}/targets Modifie les cibles de calage du lot, c’est-à-dire la spécification de pondération Silver, chaque cible étant raked ou benchmark (rôle Gestionnaire, utilisateur identifié requis)
GET /api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} Prévisualise la copie des cibles de calage d’un autre lot dans celui-ci : addable et rejected, avec les motifs ; n’écrit rien (rôle Gestionnaire)

Paramètres de requête :

  • project_id : filtre par projet

Les opérations d’étape (extraction, codage + pondération, affinage, export) se pilotent avec les outils MCP de lot et de jeux de données : voir mcp-bundle-tools.md et mcp-dataset-tools.md pour la référence complète des paramètres de qualité et d’étape.

Toutes les réponses réussies renvoient du JSON avec les codes de statut HTTP standard :

Statut Signification
200 OK La requête a abouti (y compris la création d’une ressource : l’objet créé est renvoyé dans le corps)
204 No Content Ressource supprimée avec succès

Les erreurs utilisent une enveloppe unique, composée d’un code error lisible par une machine et d’un detail lisible par un humain :

{
"error": "not_found",
"detail": "bundle 'abc123' not found"
}
Statut Code error Signification
401 unauthenticated Identifiants absents, invalides ou expirés
403 forbidden Vous n’avez pas la capacité requise, ou vous n’êtes pas propriétaire de la ressource visée
404 not_found La ressource n’existe pas (ou ne vous est pas visible)
409 conflict Requête valide, mais la ressource n’est pas encore prête (par exemple, comparer un lot dont la chaîne est encore en cours de traitement) : réessayez une fois le pipeline terminé
422 validation_error Entrée mal formée ; detail contient la liste des problèmes par champ

La spécification complète de l’API est disponible au format OpenAPI 3.0 :

GET /api/v1/openapi.json

Servez-vous de cette spécification pour générer des clients d’API typés dans le langage de programmation de votre choix.

Fenêtre de terminal
# 1. Create a project
PROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/projects \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Q1 Survey"}' | jq -r '.id')
# 2. Create a questionnaire (the QML itself is the payload — there is no file to stage)
QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/questionnaires \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg p "$PROJECT_ID" --rawfile c feedback.qml \
'{name: "Customer Feedback", project_id: $p, content: $c}')" | jq -r '.id')
# 3. Create a campaign
curl -X POST https://portor.<tenant>.askalot.io/api/v1/campaigns \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\", \"offers_ai_channel\": false}"
Fenêtre de terminal
# Import respondents from a CSV or your CRM system
for respondent in "${RESPONDENTS[@]}"; do
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "$respondent"
done