Aller au contenu
Base de connaissances

Outils de questionnaire et QML — référence des outils MCP

Les outils de questionnaire gèrent le cycle de vie du QML : sauvegarde de nouvelles versions, validation par l’analyse formelle Z3, publication d’une version sur une campagne, déplacement entre projets et dépublication. Ce cycle de vie impose des contraintes — par exemple, la dépublication est bloquée si des campagnes actives font référence au questionnaire.

Le QML d’un questionnaire est stocké dans la base de données d’Askalot sous la forme d’une chaîne de versions en ajout seul. Chaque sauvegarde ajoute une nouvelle version et y déplace la tête du questionnaire ; les versions antérieures ne sont jamais écrasées ni supprimées.

qml_name est l’adresse stable du questionnaire, de la forme projects/{project_id}/questionnaires/{questionnaire_id}.qml. Elle ressemble à un chemin et se lit comme tel, mais elle identifie un questionnaire : il n’y a ni répertoire à parcourir ni fichier à préparer. list_qml_files renvoie les adresses existantes.

Trois règles en découlent, et elles expliquent l’essentiel du comportement décrit ci-dessous :

  • Une sauvegarde nomme la version à partir de laquelle elle a été écrite. Vous composez une sauvegarde à partir d’un contenu lu un instant plus tôt, et quelqu’un d’autre a pu enregistrer entre-temps. save_qml_file et finalize_upload prennent donc base_version_id, le version_id de la réponse de lecture ou de sauvegarde dont provient votre contenu. Si la tête est toujours cette version, votre contenu devient la nouvelle tête. Si elle a bougé et que les deux modifications portent sur des lignes différentes, la fusion des deux devient la tête. Si les deux ont modifié les mêmes lignes, rien n’est écrit et la réponse est overlap.
  • La sauvegarde n’est jamais bloquée par la validation. Une ébauche, un bloc collé ou une logique inachevée doivent pouvoir être stockés : une sauvegarde consigne donc le verdict de la validation formelle sur la version enregistrée et renvoie les éventuels problèmes sous forme de warnings. Hormis une adresse qui ne correspond à aucun questionnaire dans lequel vous pouvez écrire et un appel que le schéma d’entrée rejette, une sauvegarde n’est refusée que dans les cas suivants : une base qui n’est pas une version du questionnaire (base_version_unknown), un overlap, une tête qui a bougé avant chaque tentative (head_kept_moving), un questionnaire déplacé vers un autre projet pendant la sauvegarde (questionnaire_moved), une organisation scellée (org_sealed) et un contenu transmis directement dans l’appel de plus de 32 Ko.
  • La publication, elle, peut refuser. publish_qml_file épingle une version sur une campagne, c’est-à-dire le moment où l’instrument parvient à un répondant : c’est donc le seul point de contrôle qui rejette une conception incohérente. La version épinglée est ensuite immuable pendant toute la durée de vie de cette campagne.

Liste tous les questionnaires, avec un filtre facultatif par nom.

Paramètre Type Obligatoire Par défaut Description
name string Non — Filtre par sous-chaîne, insensible à la casse
limit integer Non 100 Nombre maximal de résultats renvoyés

Renvoie : { items: [...], count, limit }


Récupère un questionnaire par son identifiant.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire

Renvoie : l’objet questionnaire ou { error }.


Crée un nouveau questionnaire à partir de contenu QML ou d’un modèle de la bibliothèque. Le questionnaire et la version 1 de son QML sont créés ensemble : un questionnaire n’existe donc jamais sans contenu.

Paramètre Type Obligatoire Par défaut Description
name string Avec content le nom du modèle Nom affiché
content string content ou template — Le YAML QML, enregistré comme version 1
template string content ou template — Un identifiant (slug) de modèle issu de list_questionnaire_templates ; la version 1 est le QML de ce modèle dans la langue language, octet pour octet
project_id string Oui — Identifiant du projet parent
description string Non — Description en texte libre
language string Non "en" ; avec template, la vôtre Code de langue. Avec template, la langue dans laquelle copier le modèle : l’une des languages de la bibliothèque. S’il est omis, votre propre langue (votre réglage, sinon la langue par défaut de votre organisation) si la bibliothèque la propose, sinon en
estimated_duration integer Non — Durée de remplissage prévue, en minutes

Indiquez content ou template, jamais les deux : fournir les deux, ou aucun des deux, est refusé, et rien n’est écrit. Un identifiant template inconnu reçoit une réponse « introuvable », et une language que la bibliothèque ne propose pas est refusée avec la liste des langues proposées.

La copie d’un modèle est écrite dans la langue dans laquelle il a été lu, et chacune des autres langues proposées par la bibliothèque l’accompagne sous forme de traduction de la version 1 : ces langues peuvent ainsi être proposées aux répondants sans étape de traduction.

Renvoie : l’objet questionnaire créé, avec le version_id et le version_number de la version 1. Ce version_id est le base_version_id à utiliser pour une première sauvegarde de ce contenu.

La création n’est pas conditionnée à la validation formelle : content peut être structurellement défectueux. À partir de content, le verdict est consigné avec la version 1, sans être imposé ; c’est la publication sur une campagne qui exige la cohérence. À partir d’un template, la validation s’exécute en arrière-plan quelques secondes après la création, comme après une sauvegarde : d’ici là, logic_validated vaut false.


Liste la bibliothèque de modèles de questionnaires : des questionnaires prêts à l’emploi (évaluations de cours, retours clients, inscriptions à un événement, accueil des patients, etc.), regroupés par catégories. Transmettez un identifiant à create_questionnaire comme template.

Paramètre Type Obligatoire Par défaut Description
language string Non la vôtre Langue de la bibliothèque dans laquelle lister les modèles. S’il est omis, votre propre langue (votre réglage, sinon la langue par défaut de votre organisation) si la bibliothèque la propose, sinon en. Une langue que la bibliothèque ne propose pas est refusée avec la liste des langues proposées
category string Non — Identifiant de catégorie ; une catégorie inconnue est refusée avec la liste des catégories
query string Non — Mots qui doivent tous figurer dans le nom ou la description d’un modèle, sans tenir compte de la casse
limit integer Non 50 Taille de page, de 1 à 100
cursor string Non — Le next_cursor de la page précédente

Renvoie : { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. Les noms, descriptions et catégories sont dans la langue language ; languages liste toutes les langues proposées par la bibliothèque, en en premier. language_fallback vaut true lorsqu’aucune language n’a été indiquée et que la bibliothèque ne propose pas encore la vôtre : la réponse est alors en anglais, et il faut le signaler à l’utilisateur. total compte tous les modèles correspondants ; suivez next_cursor tant que has_more est vrai. Aucun corps QML n’est listé : créez le questionnaire à partir d’un identifiant, puis lisez-le avec get_qml_content.


Supprime logiquement un questionnaire.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire

Renvoie : { success: true, questionnaire_id } ou une erreur.

La suppression logique insère une ligne de sauvegarde ; restore_questionnaire (ci-dessous) peut rétablir le questionnaire pendant un court délai.


Renomme un questionnaire. Il s’agit d’une simple mise à jour des métadonnées : l’adresse du questionnaire et sa chaîne de versions QML ne changent pas, et les campagnes qui y font référence continuent donc de fonctionner.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
name string Oui — Nouveau nom affiché (255 octets au maximum)

Renvoie : l’objet questionnaire mis à jour.


Restaure un questionnaire récemment supprimé logiquement et rétablit ses références. La suppression n’a jamais touché à sa chaîne de versions QML : le questionnaire restauré revient donc exactement à la version qu’il avait.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire

Renvoie : l’objet questionnaire restauré, ou une erreur si le délai de restauration est écoulé.


Liste les questionnaires QML de l’organisation. Aucun paramètre n’est requis. Le qml_name de chaque entrée peut être transmis à n’importe quel autre outil QML.

Renvoie :

{
"items": [
{
"name": "3f9c2b10-....qml",
"qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml",
"tier": "project",
"project_id": "abc123"
}
],
"count": 1
}

Obtient un résumé rapide de la version actuelle d’un questionnaire — nombre d’items et métadonnées, sans le contenu complet.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse du questionnaire issue de list_qml_files

Renvoie : { success, qml_name, items_count, metadata }


Affiche un item de la version actuelle d’un questionnaire tel qu’un répondant le voit. Un hôte qui affiche les MCP Apps (comme Claude) ouvre un panneau en lecture seule avec les vrais contrôles de l’item ; tout autre hôte reçoit le même item sous forme de texte JSON.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse du questionnaire issue de list_qml_files
item_id string Oui — L’id de l’item

Renvoie : les champs affichés de l’item (id, kind, title, input, ainsi que questions, rows ou columns lorsque l’item en possède), le balisage éventuel de son texte étant assaini. Un item ou une adresse inconnus produisent une erreur d’outil.


Récupère le YAML brut de la version actuelle d’un questionnaire.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse du questionnaire

Renvoie : { success, qml_name, content, size_bytes, version_id, version_number } pour un contenu de 32 Ko au plus. version_id désigne la version que constitue content ; transmettez-le comme base_version_id lorsque vous enregistrez un contenu écrit à partir de cette réponse.

Au-delà de 32 Ko, le contenu n’est pas inclus dans la réponse, qui prend alors la forme { success, qml_name, download_url, size_bytes, version_id, version_number, note }, où download_url est un lien de courte durée (réutilisable jusqu’à son expiration) que vous récupérez directement en HTTPS (sans autre authentification). Le lien sert version_id, même si une sauvegarde a déplacé la tête depuis votre demande : ses octets correspondent donc bien à la version que vous indiquez comme base_version_id lors de la sauvegarde. Rappelez get_qml_content si le lien a expiré.


Enregistre du contenu QML dans un questionnaire existant, écrit à partir d’une version que vous nommez. La sauvegarde n’est jamais bloquée par un YAML défectueux ou des violations du schéma : un brouillon en cours, pas encore valide, est tout de même enregistré, et les problèmes sont renvoyés dans une liste warnings au lieu de faire rejeter l’écriture.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse d’un questionnaire existant
content string Oui — Contenu YAML QML, jusqu’à 32 Ko
base_version_id string Oui — La version à partir de laquelle le contenu a été écrit : le version_id de votre réponse la plus récente de get_qml_content, de create_questionnaire ou de sauvegarde pour ce questionnaire
project_id string Non — S’il est indiqué, il doit correspondre au projet du questionnaire ; une discordance est refusée plutôt qu’ignorée

Lisez d’abord, puis enregistrez. Appelez get_qml_content, appliquez votre modification au contenu renvoyé, et enregistrez avec son version_id comme base_version_id. Après une sauvegarde, la sauvegarde suivante nomme le version_id que celui-ci a renvoyé, jamais un plus ancien.

Renvoie : { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.

Ce qui s’est passé Dans la réponse
La base était encore la tête created: true, merged: false. Votre contenu devient la nouvelle tête
Quelqu’un a enregistré entre-temps, sur d’autres lignes created: true, merged: true, content_changed: true. La tête contient les deux modifications, et content la transmet : elle remplace votre copie. Les lignes que vous n’avez pas écrites sont celles de l’autre auteur
Votre contenu est déjà la tête created: false. Rien n’est écrit
Votre contenu est identique à sa base et la tête a bougé created: false, content_changed: true, avec le content de la tête

content n’est inclus que lorsque le contenu enregistré fait moins de 32 Ko ; sinon, content_note indique d’appeler get_qml_content. warnings est absent lors d’une sauvegarde sans problème ; c’est une liste de problèmes d’analyse ou de schéma pour un brouillon enregistré mais imparfait.

Une sauvegarde qui n’écrit rien répond { success: false, error, detail } :

error Signification Que faire
overlap Quelqu’un a enregistré entre-temps et modifié les mêmes lignes. Porte head_version_id, head_version_number, conflict_count Appelez get_qml_content, appliquez votre modification à ce qu’il renvoie, et enregistrez avec son version_id. Ne renvoyez pas le même contenu sous l’identifiant plus récent : cela écraserait l’autre sauvegarde
base_version_unknown base_version_id est vide, n’est pas un identifiant de version, ou n’est pas une version de ce questionnaire Appelez get_qml_content et enregistrez avec le version_id qu’il renvoie
head_kept_moving Le questionnaire a été enregistré de nouveau avant chacune des trois tentatives Relisez et réessayez
org_sealed L’organisation est scellée Aucune écriture n’est possible
questionnaire_moved Le questionnaire a été déplacé vers un autre projet pendant la sauvegarde Appelez list_qml_files pour obtenir son adresse actuelle, lisez-le avec get_qml_content et enregistrez de nouveau

La validation formelle s’exécute en arrière-plan, quelques secondes après la sauvegarde, sur la version qui est alors la tête (la vôtre, ou la fusion), et son verdict est consigné sur cette version : la cohérence d’une version reste ainsi vérifiable plus tard, même après d’autres modifications. D’ici là, logic_validated vaut null dans la réponse de sauvegarde et logic_validation_note le signale, et get_questionnaire indique logic_validated: false ; il renvoie le verdict dès qu’il est disponible, et validate_qml_file le fournit à la demande. Une sauvegarde qui introduit une régression fait passer le questionnaire à l’état non validé sans bloquer l’écriture ; sa publication sur une campagne est refusée jusqu’à sa correction.

Une adresse qui ne correspond à aucun questionnaire est refusée — appelez d’abord create_questionnaire.

Un contenu de plus de 32 Ko est refusé avec {"error": "content_too_large_for_inline_save"}, et rien n’est écrit. Utilisez request_upload_url / finalize_upload (ci-dessous) plutôt que de tronquer le contenu.


Une procédure en deux temps pour enregistrer un contenu QML trop volumineux pour la limite de 32 Ko qu’impose save_qml_file au contenu transmis directement dans l’appel. Le contenu lui-même n’apparaît jamais dans un appel d’outil : vous demandez un identifiant de téléversement, téléversez les octets directement en HTTPS, puis finalisez.

  1. request_upload_url(qml_name, project_id?) — crée un identifiant de téléversement de courte durée, à usage unique et limité en taille.

    Renvoie : { upload_url, artifact_id, max_size_bytes, expires_in }

  2. Téléversez les octets QML bruts directement vers upload_url (une requête HTTP PUT, en dehors de l’appel d’outil MCP).

  3. finalize_upload(artifact_id, base_version_id) — enregistre le contenu téléversé exactement comme save_qml_file l’enregistrerait sur cette base : accepté, fusionné avec une sauvegarde plus récente, ou refusé. base_version_id est obligatoire et a le même sens que pour save_qml_file. Peut être réessayé sans risque avec le même artifact_id : après une finalisation qui a enregistré, ou qui a répondu overlap, une nouvelle tentative renvoie la première réponse et n’écrit rien, quelle que soit la base indiquée.

    Renvoie : la même enveloppe que save_qml_file

    Un overlap consomme l’identifiant de téléversement, car les octets téléversés ont été écrits à partir de l’ancienne version : relisez, réappliquez votre modification et téléversez le résultat via un nouvel identifiant. base_version_unknown et head_kept_moving conservent l’identifiant : un appel corrigé enregistre le même téléversement.


Exécute la validation formelle SMT Z3 sur la version actuelle d’un questionnaire. Analyse l’accessibilité, la cohérence et la satisfaisabilité des postconditions pour chaque item.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse du questionnaire

Renvoie :

{
"is_valid": true,
"item_count": 12,
"block_count": 3,
"item_classifications": {
"q_age": {
"precondition": "REACHABLE",
"postcondition": "CONTINGENT"
}
},
"statistics": {
"preconditions": {"REACHABLE": 11, "NEVER": 1},
"postconditions": {"CONTINGENT": 8, "TAUTOLOGICAL": 3, "INFEASIBLE": 1}
},
"issues": [
{
"item_id": "q_unreachable",
"severity": "error",
"type": "unreachable_item",
"message": "Item is unreachable",
"suggestion": "Check preconditions"
}
],
"validation_report": "..."
}

États des préconditions (l’item peut-il être atteint ?) :

État Signification
REACHABLE L’item peut être atteint par au moins un chemin du parcours
NEVER L’item est inaccessible — code mort
UNKNOWN L’analyse n’a pas pu déterminer l’accessibilité

États des postconditions (les conditions de l’item sont-elles satisfaisables ?) :

État Signification
TAUTOLOGICAL La condition est toujours vraie (redondante)
CONTINGENT La condition dépend des réponses (cas normal)
INFEASIBLE La condition ne peut jamais être satisfaite
UNKNOWN L’analyse n’a pas pu conclure
Type Gravité Description
unreachable_item error La précondition vaut NEVER — item mort
code_answered_item warning Un codeBlock enregistre la réponse de l’item avant que le parcours ne l’atteigne, sur chaque parcours où sa condition d’accès est vraie : l’item n’est donc jamais posé. Déplacez le codeBlock après l’item si celui-ci doit être posé
infeasible_postcondition error La postcondition ne peut jamais être satisfaite
globally_false_postcondition error La postcondition est toujours fausse
tautological_postcondition warning La postcondition est toujours vraie (redondante)
comment_titled_as_question warning Un Comment, purement informatif, a pour titre une demande : il s’affiche sans champ permettant d’y répondre
roster_subject_not_answerable warning Le subjectFrom d’un Roster nomme un item qui ne peut jamais fournir de sujet (absent, hors du bloc, ou un Comment)
none_unsafe_reference warning Une condition compare ou calcule sur un item qui n’est pas posé sur chaque chemin qui y mène — le résultat de cet item vaut None et le prédicat lève une exception. L’égalité avec None est sûre et n’est pas signalée
inexact_condition warning Une condition lit un item qui peut rester sans réponse, à un endroit où le validateur ne peut pas déterminer si la lecture de None la fait échouer (sous not, dans un opérande de or autre que le dernier, ou n’importe où dans une postcondition). Une contradiction est tout de même signalée, mais la condition n’est pas prouvée toujours vraie. Testez d’abord l’existence d’une réponse : q.outcome is not None and (…) dans une précondition, q.outcome is None or (…) dans une postcondition
uninitialized_read warning Une condition ou un codeBlock lit une variable qu’un répondant peut atteindre avant toute affectation — elle est affectée plus tard, sur une seule branche, ou par un item que sa propre condition d’accès peut faire sauter. La lecture lève une exception : une précondition fait sauter l’item, tandis qu’une postcondition accepte la réponse sans la vérifier et qu’un codeBlock s’arrête en cours de route — deux cas qui excluent l’enquête des jeux de données. Affectez une valeur par défaut dans codeInit, affectez sur les deux branches, ou soumettez la lecture à la même condition que l’affectation
self_assignment warning Une instruction de codeBlock affecte une valeur à elle-même (q.outcome = q.outcome) — elle ne change rien mais se lit comme une dérivation
mandated_answer_postcondition warning Une postcondition n’admet qu’une seule réponse d’un contrôle à choix : un répondant qui donne une autre réponse ne peut pas avancer, et cette réponse n’est jamais enregistrée. Orientez plutôt le parcours selon la réponse
combinable_none_option warning Une option de Checkbox du type « Aucune de ces réponses » peut être cochée en même temps que les options qu’elle exclut, et aucune postcondition ne refuse cette combinaison
questionnaire_level_condition warning Une clé precondition/postcondition au niveau racine. Les conditions ne sont évaluées qu’au niveau des items et des blocs : celle-ci ne s’exécute donc jamais
language_not_judged warning La langue du questionnaire ne fait pas partie des langues prises en charge : les contrôles fondés sur les mots n’ont donc pas été exécutés, à savoir la partie formulation de comment_titled_as_question (un ? dans le titre d’un Comment reste vérifié) et combinable_none_option. Vérifiez-les vous-même
file_not_found error L’adresse ne correspond à aucun questionnaire
validation_error error Exception lors de l’analyse syntaxique ou de l’analyse formelle

Calcule une grille d’évaluation de la qualité de conception (dimensions D2–D8) pour la version actuelle d’un questionnaire. Utilisez-la après que validate_qml_file a signalé zéro erreur : la validation prouve la cohérence logique ; cette grille évalue la qualité de conception (économie de l’instrument, densité des contrôles de qualité, couverture de vérification, complexité structurelle, cohérence de l’ordre, diversité des parcours et équilibre de la charge). La densité des contrôles de qualité se mesure sur les saisies numériques du questionnaire — les réponses qu’un répondant tape ou règle avec un curseur, là où une postcondition ajoute une borne de validité que le contrôle lui-même n’impose pas. Les items à choix sont exclus de ce taux, car leur jeu de libellés fixe déjà la réponse ; une postcondition qui lie un choix à un autre est signalée à part, comme contrôle de cohérence. Déterministe et indicative : les notes n’affectent jamais is_valid ni la publication.

Paramètre Type Obligatoire Par défaut Description
qml_name string Oui — Adresse du questionnaire

Renvoie :

{
"dimensions": {
"instrument_economy": {
"id": "D2",
"grade": "strong",
"metrics": { },
"offenders": [{"item_id": "...", "detail": "..."}],
"truncated": false
}
},
"item_count": 12,
"notes": []
}

La grade de chaque dimension vaut strong, adequate, weak ou not_applicable. Une adresse inconnue ou un échec de l’analyse renvoie { error }.


Publie un questionnaire sur une campagne — la porte d’entrée du terrain, et le seul outil de cette référence qui refuse une conception incohérente.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire à mettre sur le terrain
campaign_id string Oui — UUID de la campagne sur laquelle l’épingler

La version actuelle du questionnaire est validée formellement, le verdict est consigné sur cette version, et seul un verdict sans erreur l’épingle sur la campagne.

Renvoie : { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }

En cas de refus : { error, issues } — issues liste les problèmes de gravité « erreur » à corriger. Rien n’est épinglé : la campagne continue de diffuser ce qu’elle diffusait.

La campagne doit déjà faire référence à ce questionnaire ; si elle en diffuse un autre, rattachez-la d’abord avec update_campaign_questionnaire.


Déplace un questionnaire vers un autre projet. L’identifiant du questionnaire reste stable et sa chaîne de versions n’est pas modifiée : les campagnes qui y font référence — y compris celles épinglées sur une version antérieure — continuent de fonctionner. Un déplacement n’est pas une modification.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
target_project_id string Oui — UUID du projet de destination

Renvoie : { success, questionnaire_id, qml_name } — qml_name est la nouvelle adresse.


Retire un questionnaire de son projet en le supprimant logiquement. Sa chaîne de versions QML est conservée — une campagne terminée peut encore être épinglée sur l’une de ces versions : la dépublication retire donc le questionnaire de votre espace de travail sans effacer ce qui a été diffusé sur le terrain. Bloqué si le questionnaire a des campagnes actives.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire

Renvoie : { success, questionnaire_id } ou une erreur.


Une traduction est un texte traduit associé à une version de questionnaire, une par langue. Elle ne remplace que le texte visible par les répondants ; les identifiants, les codes d’option, les conditions et le verdict Z3 restent ceux de la source. Seule une traduction complète est proposée aux répondants. Notions, gel et sélecteur de langue du répondant : Traduire un questionnaire.

Chaque outil de traduction nomme questionnaire_id, version_id (le version_id renvoyé par get_qml_content ou par une sauvegarde) et, sauf pour la liste, locale (en, es, fr, de ou hu, jamais la langue source du questionnaire lui-même). Chacun reporte d’abord les traductions de la version précédente sur la version nommée : une version nouvellement enregistrée contient donc déjà tous les textes dont la source n’a pas changé.

Les clés de texte désignent chacune un texte visible par les répondants : questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (libellés d’option, par code), item:<id>/rows/<n> et /columns/<n> (matrice), item:<id>/questions/<n> (groupe de questions), item:<id>/left, /right, /on, /off, /placeholder, et .../postcondition/<n>/hint (le message affiché lorsqu’une réponse est refusée). Lisez les clés exactes d’une version dans les source_texts de get_qml_translation.

Toutes les traductions d’une version, par langue.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
version_id string Oui — Une version de ce questionnaire

Renvoie : { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, avec une entrée pour chaque langue prise en charge sauf la langue source : la liste nomme donc aussi les langues que personne n’a commencées (started: false, avec untranslated laissé vide : toutes les clés le sont, et get_qml_translation les liste) et celles dont la traduction a été supprimée (withdrawn: true). untranslated liste les clés de texte encore manquantes ; frozen signifie qu’une enquête a reçu des réponses dans cette langue, de sorte que la traduction n’accepte plus ni sauvegarde ni suppression ; human_edited signifie qu’une personne l’a modifiée dans l’éditeur.

La traduction d’une langue, avec la source qu’elle traduit.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
version_id string Oui — Une version de ce questionnaire
locale string Oui — Langue cible

Renvoie : les champs de la liste pour cette langue, plus texts (clé → texte traduit), source_language et source_texts (chaque clé traduisible → son texte source, dans l’ordre du document). Une langue encore dépourvue de traduction renvoie des texts vides et updated_at: null.

Enregistre le texte traduit d’une langue. La sauvegarde est partielle : texts est fusionné avec la traduction enregistrée, et chaque clé que vous omettez conserve son texte enregistré ; pour combler les manques, il suffit donc d’envoyer les clés listées dans untranslated.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
version_id string Oui — Une version de ce questionnaire
locale string Oui — Langue cible
texts object Oui — Clé de texte → texte traduit
base_updated_at string | null Oui — Le updated_at renvoyé par votre lecture ; null si elle n’a renvoyé aucune traduction enregistrée

Renvoie : la traduction enregistrée (texts, complete, untranslated, frozen, human_edited, updated_at). Une sauvegarde suivante nomme le updated_at renvoyé par celui-ci. Une sauvegarde effectuée via MCP ou l’API est consignée comme écrit par un agent et ne marque jamais la traduction comme human_edited.

Refus Signification Que faire
Clés invalides (requête incorrecte, une ligne par clé) Une clé nomme un item, un bloc ou un code d’option absent de la source, un index hors limites, une liste positionnelle (rows, columns, questions, indications de postcondition) envoyée en partie, une valeur qui n’est pas du texte, ou du balisage tel que <script> Corrigez exactement les clés nommées, puis enregistrez de nouveau
translation_conflict (409) La traduction a changé depuis votre lecture, généralement à la suite d’une modification par un chercheur Relisez avec get_qml_translation, réappliquez votre modification et enregistrez avec le nouveau updated_at
translation_frozen (409) Une enquête a reçu des réponses dans cette langue sur cette version Ne réessayez pas. Enregistrez une nouvelle version du questionnaire, traduisez-la, puis faites passer la campagne sur cette version
Langue source (requête incorrecte) La langue est celle du questionnaire lui-même Modifiez directement le QML, ou traduisez dans une autre langue
Introuvable La version n’est pas une version de ce questionnaire Lisez le questionnaire avec get_qml_content et nommez le version_id qu’il renvoie

Supprime la traduction d’une version dans une langue. Une traduction gelée est refusée (translation_frozen), et une langue sans traduction est introuvable.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — UUID du questionnaire
version_id string Oui — Une version de ce questionnaire
locale string Oui — Langue à supprimer

Renvoie : { questionnaire_id, version_id, locale, deleted: true }.


Cas Réponse
Dépublication avec des campagnes actives {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"}
Publication d’une version incohérente {"error": "...", "issues": [...]} — rien n’est épinglé
Publication sur une campagne qui diffuse un autre questionnaire {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."}
Déjà dans le projet cible {"error": "Questionnaire is already in this project"}

Chaque outil ne recherche les questionnaires qu’au sein de votre propre organisation. Une adresse appartenant à une autre organisation est indiscernable d’une adresse inexistante, et un project_id qui ne correspond pas au projet du questionnaire est refusé plutôt qu’ignoré en silence.

Cas Réponse
Questionnaire introuvable {"error": "Questionnaire {id} not found"}
Contexte d’organisation non défini {"error": "Organization context not set"}
L’adresse ne correspond à aucun questionnaire {"error": "QML document '{name}' not found for this organization"}
La sauvegarde ne nomme aucune base utilisable {"success": false, "error": "base_version_unknown", "detail": "..."}
La sauvegarde chevauche une sauvegarde plus récente {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n}
Erreur d’analyse du QML {"error": "Failed to parse QML: {details}"}