Activer l’accès en écriture sur un jeton
L’accès en écriture s’active jeton par jeton. Il est désactivé par défaut sur chaque jeton, y compris ceux créés avant l’arrivée des commandes. Vous n’avez pas besoin de renouveler un jeton : continuez à l’utiliser et activez-y les écritures. Un Propriétaire ou un Manager de l’équipe active l’accès en écriture dans les réglages du jeton, sous Gestion de l’équipe > API REST. D’ici là, chaque commande faite avec ce jeton renvoie403 API_KEY_READ_ONLY, et les lectures continuent de fonctionner. Consultez Jetons d’API.
Les jetons sont limités à l’équipe et ne portent aucun rôle d’utilisateur. N’activez les écritures que sur les jetons qui en ont besoin, et relisez Authentification avant de partager un jeton avec une intégration.
Choisir une commande
Réessayer sans risque
ChaquePOST qui modifie des données exige un en-tête Idempotency-Key : une valeur unique que vous choisissez pour chaque opération logique, de 255 caractères au maximum. Le POST /brands/{brandId}/runs/estimate, qui ne modifie rien, fait exception : il n’exige pas Idempotency-Key, mais utilise tout de même l’autorisation et les limites de débit des commandes.
Cet exemple synthétique crée un workspace en brouillon :
- Le même
Idempotency-Keyavec les mêmes paramètres de chemin et le même corps parsé rejoue une réponse terminée, avec son statut, sonLocationet sonETag. La réponse inclutIdempotent-Replay: true. - La même clé avec des paramètres de chemin ou un corps différents renvoie
409IDEMPOTENCY_CONFLICT. - Une requête en cours ou un résultat non résolu renvoie
409IDEMPOTENCY_IN_PROGRESS. Lisez la ressource avant de démarrer une nouvelle opération logique.
Éviter les mises à jour perdues
Les commandesPATCH et DELETE exigent un en-tête If-Match portant l’ETag que vous avez lu en dernier. Les ressources modifiables d’un workspace exposent une version ; les audits de prospection exposent une revision. Les deux renvoient l’ETag correspondant à la lecture. Traitez ces valeurs comme des jetons de concurrence opaques : copiez l’ETag renvoyé tel quel, ne calculez pas la version suivante et ne supposez pas que les versions augmentent de un.
Sur
412, relisez la ressource et réconciliez votre modification avec l’état le plus récent. If-Match: * accepte n’importe quelle version actuelle et supprime la protection contre l’écrasement d’une modification concurrente. Une nouvelle tentative avec une ancienne version peut renvoyer 412 même si votre première requête a réussi ; lisez la ressource pour déterminer son état.
Utilisez ?view=configuration sur les listes de prompts, de Topics et de Tags pour récupérer les champs modifiables et les versions, y compris les prompts archivés et les libellés sans analytics. Utilisez le détail de configuration du prompt, le détail d’un Topic ou le détail d’un Tag pour lire la ressource et son ETag. Le suivi d’un workspace a sa propre lecture de détail et son propre ETag.
Préserver les valeurs de configuration
PourPATCH, un champ omis garde sa valeur actuelle. N’envoyez null que lorsque le schéma de l’endpoint l’autorise. Par exemple, description: null efface la description d’un workspace et keywordId: null détache un prompt de son Topic. Pour un prompt, frequency: null efface la fréquence enregistrée qui remplace celle du workspace ; c’est distinct de la valeur explicite "NONE". tagIds: [] retire tous les Tags du prompt, sauf le Tag système Branded ou Non-branded, que Qwairy pose d’après le texte du prompt dans un workspace créé à partir de la v1.21.
Ne convertissez pas null en chaîne vide, en zéro ou en tableau vide. Lisez et écrivez la représentation de configuration, y compris les prompts archivés et les libellés sans analytics, lorsque vous synchronisez des réglages.
Interpréter les réponses des commandes
Pour
201 et 202, suivez Location avec GET pour lire l’état actuel. Un 202 ne prouve pas que la collecte des réponses des fournisseurs est terminée. Utilisez le détail d’un run ou le détail d’un audit de prospection pour les champs exposés par ce flux.
Les commandes de prompts en masse renvoient 200 avec un résultat individuel pour chaque prompt : updated, unchanged ou not_found. Examinez chaque élément ; le statut HTTP seul ne signifie pas que tous les prompts demandés ont été modifiés. Une requête en masse accepte 20 prompts au plus et repose sur l’idempotence, sans exiger If-Match.
L’acceptation de suggestions de prompts renvoie aussi 200 avec un résultat pour chaque élément. Examinez là aussi chaque élément.
Prévisualiser avec dryRun
Ces commandes acceptentdryRun: true, qui valide la requête et renvoie le résultat sans rien modifier :
- Mettre à jour des prompts en masse
- Mettre à jour le suivi
- Lancer un audit de pages, qui renvoie un audit
PREVIEWavec lescreditsReservedqu’il réserverait - Accepter des suggestions de prompts, qui indique aussi la consommation récurrente de crédits dans
dailyCredits
Être notifié à la fin du travail
Une réponse202 signifie que le travail a été accepté. Interrogez la ressource indiquée par Location, ou abonnez un webhook d’intégration à l’événement de fin correspondant. Les webhooks d’intégration sont disponibles avec les offres Business, Agency Business et Enterprise.
Automatiser un audit de prospection
Une équipe agence sur une offre avec écriture peut exécuter le parcours d’audit de prospection avec relecture en trois commandes :- Créez un audit de prospection avec un
Idempotency-Key. - Lisez-le avec Obtenir un audit de prospection, puis enregistrez les prompts relus avec l’
ETagrenvoyé lorsque la relecture des prompts est prête. - Confirmez l’audit de prospection avec un nouvel
Idempotency-Keypour mettre en file la collecte de réponses facturable.
autoStartResponses=true à la création uniquement si vous voulez volontairement sauter la relecture manuelle des prompts. Les nouvelles tentatives d’audit de prospection et les exports générés côté serveur restent des opérations du tableau de bord. Les clients MCP peuvent exécuter le même cycle de vie avec des scopes d’écriture distincts, des aperçus et des jetons de confirmation ; consultez Accès en écriture MCP.
Format des erreurs
Chaque erreur de commande, y compris l’authentification401 et la limite de débit 429, porte un code stable et un identifiant de requête :
error.code et conservez error.requestId lorsque vous contactez le support. Les réponses de commande incluent aussi X-Request-Id. Les enveloppes d’authentification et de limite de débit en lecture diffèrent ; consultez Codes d’erreur pour un client qui gère les deux formes.
Un
503 SERVICE_UNAVAILABLE couvre aussi les écritures suspendues. Dans les deux cas, la commande ne s’est pas exécutée.
Une ressource appartenant à une autre équipe est traitée comme introuvable. Les commandes sur une seule ressource renvoient 404 ; les commandes de prompts en masse peuvent signaler not_found par élément. Les autres conflits 409, les versions périmées 412 et les préconditions manquantes 428 demandent une réconciliation ou une requête corrigée avant de réessayer.
Limites de débit
Les commandes ont leur propre budget, distinct des lectures : 120 requêtes par minute et 5 000 par jour par équipe. Cela inclut les estimations de run et les rejeux idempotents. Le trafic de commandes ne consomme pas le budget de requêtes de lecture. RespectezRetry-After sur 429. Si le limiteur d’écriture est indisponible ou si les écritures sont suspendues, la requête renvoie 503 SERVICE_UNAVAILABLE avant l’exécution de la commande et rien ne change. Utilisez un backoff borné et la même clé d’idempotence lorsque vous réessayez un POST qui modifie des données. Consultez Limites de débit.
Périmètre et limites du cycle de vie
- Créer un workspace ne lance jamais d’analyse ni de run facturable. Cela crée un
DRAFT; vous l’activez quand vous êtes prêt. - Archiver un prompt conserve ses réponses et son historique, et peut être annulé.
- Supprimer un Topic ou un Tag ne retire que le libellé. Les prompts sont détachés, jamais supprimés. Les Tags système
BrandedetNon-brandedne peuvent être ni créés, ni renommés, ni mis à jour, ni supprimés : ces requêtes renvoient400 INVALID_REQUEST. - Les crédits peuvent être consultés avec
GET /api/v1/credits, mais l’allocation, les transferts et les achats restent des actions du tableau de bord. - Les runs peuvent être estimés, lancés, listés et lus. L’API publique v1 ne fournit pas de commande d’annulation ou de nouvelle tentative de run.
- Créer un audit de prospection prépare ses prompts. Le confirmer, ou activer la collecte automatique des réponses à la création, lance le flux de réponses facturable.
L’appartenance à l’équipe, les rôles, les invitations et l’accès des Lecteurs aux workspaces ne font pas partie de l’API. Gérez-les dans le tableau de bord.

