> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Écrire des données

> Créez et modifiez des ressources Qwairy depuis vos systèmes : écriture activée par jeton, réessais par clés d’idempotence, ETag contre les mises à jour perdues.

Les commandes de l’API v1 vous permettent de gérer depuis vos propres systèmes les workspaces, prompts, Topics, Tags, le suivi, les runs, les actions, le Diagnostic du site, les suggestions de prompts, les endpoints de webhook et le cycle de vie principal des audits de prospection. La référence contient **28 commandes** : 27 créent ou modifient des ressources, et une estime un run sans le lancer ni réserver de crédits.

La lecture démarre avec Growth ou Agency Growth. Les commandes exigent une offre **Business**, **Agency Business** ou **Enterprise** active et l’accès en écriture activé sur le jeton d’API. Les commandes d’audit de prospection exigent aussi une équipe agence. Consultez l’[inventaire complet des endpoints](https://docs.qwairy.co/fr/developers/endpoints/index.md).

## 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](https://www.qwairy.co/dashboard/team/api). D’ici là, chaque commande faite avec ce jeton renvoie `403` `API_KEY_READ_ONLY`, et les lectures continuent de fonctionner. Consultez [Jetons d’API](https://docs.qwairy.co/fr/developers/api-keys.md#activer-l’accès-en-écriture).

> [!WARNING]
>
> Une clé valide sur Growth ou Agency Growth reçoit `403` `INSUFFICIENT_PLAN` pour les commandes. Les équipes inactives ou les abonnements sans accès à l’API échouent d’abord à l’authentification avec `401`.

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](https://docs.qwairy.co/fr/developers/authentication.md) avant de partager un jeton avec une intégration.

## Choisir une commande

| Ressource | Commandes |
| - | - |
| Workspaces | [Créer](https://docs.qwairy.co/fr/developers/endpoints/brands/create.md), [mettre à jour](https://docs.qwairy.co/fr/developers/endpoints/brands/update.md), [mettre à jour le suivi](https://docs.qwairy.co/fr/developers/endpoints/brands/update-monitoring.md) |
| Topics | [Créer](https://docs.qwairy.co/fr/developers/endpoints/keywords/manage.md), [mettre à jour](https://docs.qwairy.co/fr/developers/endpoints/keywords/update.md), [supprimer](https://docs.qwairy.co/fr/developers/endpoints/keywords/delete.md) |
| Tags | [Créer](https://docs.qwairy.co/fr/developers/endpoints/tags/create.md), [mettre à jour](https://docs.qwairy.co/fr/developers/endpoints/tags/update.md), [supprimer](https://docs.qwairy.co/fr/developers/endpoints/tags/delete.md) |
| Prompts | [Créer](https://docs.qwairy.co/fr/developers/endpoints/prompts/manage.md), [mettre à jour ou archiver](https://docs.qwairy.co/fr/developers/endpoints/prompts/update.md), [mettre à jour en masse](https://docs.qwairy.co/fr/developers/endpoints/prompts/bulk.md) |
| Runs | [Estimer](https://docs.qwairy.co/fr/developers/endpoints/runs/estimate.md), [lancer](https://docs.qwairy.co/fr/developers/endpoints/runs/manage.md) |
| Audits de prospection | [Créer](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/create.md), [enregistrer les prompts relus](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/save-prompts.md), [confirmer](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/confirm.md) |
| Actions | [Mettre à jour un statut](https://docs.qwairy.co/fr/developers/endpoints/actions/update-status.md) |
| Diagnostic du site | [Ajouter des pages](https://docs.qwairy.co/fr/developers/endpoints/site-diagnostics/add-pages.md), [lancer un audit](https://docs.qwairy.co/fr/developers/endpoints/site-diagnostics/start-audit.md) |
| Suggestions de prompts | [Générer](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/generate.md), [accepter](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/accept.md) |
| Endpoints de webhook | [Créer](https://docs.qwairy.co/fr/developers/endpoints/webhooks/create.md), [mettre à jour](https://docs.qwairy.co/fr/developers/endpoints/webhooks/update.md), [supprimer](https://docs.qwairy.co/fr/developers/endpoints/webhooks/delete.md), [renouveler le secret](https://docs.qwairy.co/fr/developers/endpoints/webhooks/rotate-secret.md), [tester](https://docs.qwairy.co/fr/developers/endpoints/webhooks/test.md), [renvoyer](https://docs.qwairy.co/fr/developers/endpoints/webhooks/redeliver.md) |

## Réessayer sans risque

Chaque `POST` 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 :

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: create-example-workspace-001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example workspace", "domain": "example.com"}'
```

La fenêtre de rejeu est de **24 heures**, limitée à la même clé d’API et à la même commande :

* Le même `Idempotency-Key` avec les mêmes paramètres de chemin et le même corps parsé rejoue une réponse terminée, avec son statut, son `Location` et son `ETag`. La réponse inclut `Idempotent-Replay: true`.
* La même clé avec des paramètres de chemin ou un corps différents renvoie `409` `IDEMPOTENCY_CONFLICT`.
* Une requête en cours ou un résultat non résolu renvoie `409` `IDEMPOTENCY_IN_PROGRESS`. Lisez la ressource avant de démarrer une nouvelle opération logique.

Réessayez une requête expirée avec la même clé d’API, la même commande, la même clé d’idempotence et la même charge utile. Une autre clé d’API ou une fenêtre de rejeu expirée ne réutilise pas la réponse enregistrée. Réconciliez l’état actuel avant d’émettre une nouvelle clé après un résultat incertain, surtout pour les opérations qui réservent des crédits.

## Éviter les mises à jour perdues

Les commandes `PATCH` 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.

```bash theme={null}
# 1. Read the current state
curl -i "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
# ETag: "4"

# 2. Write against that exact version
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "4"' \
  -H "Content-Type: application/json" \
  -d '{"status": "LIVE"}'
```

| Situation | Réponse |
| - | - |
| `If-Match` absent | `428` `PRECONDITION_REQUIRED` |
| La ressource a changé depuis votre lecture | `412` `PRECONDITION_FAILED` |

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](https://docs.qwairy.co/fr/developers/endpoints/keywords/get.md) ou le [détail d’un Tag](https://docs.qwairy.co/fr/developers/endpoints/tags/get.md) 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

Pour `PATCH`, 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

| Statut | Signification |
| - | - |
| `200` | La commande est terminée, ou une estimation de run a été renvoyée |
| `201` | Un workspace, un prompt, un Topic, un Tag ou un endpoint de webhook a été créé |
| `202` | Un run, un audit de prospection, un audit de pages, une génération de suggestions de prompts ou un envoi de webhook a été accepté pour un traitement asynchrone |
| `204` | Un endpoint de webhook a été supprimé |

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](https://docs.qwairy.co/fr/developers/endpoints/runs/get.md) 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](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/accept.md) renvoie aussi `200` avec un résultat pour chaque élément. Examinez là aussi chaque élément.

## Prévisualiser avec dryRun

Ces commandes acceptent `dryRun: true`, qui valide la requête et renvoie le résultat sans rien modifier :

* [Mettre à jour des prompts en masse](https://docs.qwairy.co/fr/developers/endpoints/prompts/bulk.md)
* [Mettre à jour le suivi](https://docs.qwairy.co/fr/developers/endpoints/brands/update-monitoring.md)
* [Lancer un audit de pages](https://docs.qwairy.co/fr/developers/endpoints/site-diagnostics/start-audit.md), qui renvoie un audit `PREVIEW` avec les `creditsReserved` qu’il réserverait
* [Accepter des suggestions de prompts](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/accept.md), qui indique aussi la consommation récurrente de crédits dans `dailyCredits`

## Être notifié à la fin du travail

Une réponse `202` signifie que le travail a été accepté. Interrogez la ressource indiquée par `Location`, ou abonnez un [webhook d’intégration](https://docs.qwairy.co/fr/developers/integration-webhooks/overview.md) à 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 :

1. [Créez un audit de prospection](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/create.md) avec un `Idempotency-Key`.
2. Lisez-le avec [Obtenir un audit de prospection](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/get.md), puis [enregistrez les prompts relus](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/save-prompts.md) avec l’`ETag` renvoyé lorsque la relecture des prompts est prête.
3. [Confirmez l’audit de prospection](https://docs.qwairy.co/fr/developers/endpoints/pitch-audits/confirm.md) avec un nouvel `Idempotency-Key` pour mettre en file la collecte de réponses facturable.

Définissez `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](https://docs.qwairy.co/fr/mcp/write/overview.md).

## Format des erreurs

Chaque erreur de commande, y compris l’authentification `401` et la limite de débit `429`, porte un code stable et un identifiant de requête :

```json theme={null}
{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "A workspace cannot move from LIVE to DRAFT.",
    "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
  }
}
```

Appuyez-vous sur `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](https://docs.qwairy.co/fr/developers/errors.md) pour un client qui gère les deux formes.

| Code | Signification |
| - | - |
| `INSUFFICIENT_PLAN` | L’offre n’inclut pas l’accès en écriture |
| `API_KEY_READ_ONLY` | Les écritures ne sont pas activées sur ce jeton d’API |
| `IDEMPOTENCY_CONFLICT` | Clé réutilisée avec un corps différent |
| `IDEMPOTENCY_IN_PROGRESS` | Le résultat est incertain ; réconciliez avant tout nouveau travail |
| `INVALID_STATE_TRANSITION` | Le changement de cycle de vie demandé n’est pas autorisé |
| `RESOURCE_BUSY` | Un travail est en cours ; lisez son état avant de réessayer |
| `QUOTA_EXCEEDED` | Une limite de l’offre est atteinte |
| `INSUFFICIENT_CREDITS` | Pas assez de crédits pour cette opération |
| `SERVICE_UNAVAILABLE` | Le limiteur d’écriture est indisponible ; réessayez sous peu |

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.

Respectez `Retry-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](https://docs.qwairy.co/fr/developers/rate-limits.md).

## 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 `Branded` et `Non-branded` ne peuvent être ni créés, ni renommés, ni mis à jour, ni supprimés : ces requêtes renvoient `400 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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.