> ## 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.

# Intégrer un client avec l’API

> Créez un workspace DRAFT, configurez les Topics, Tags, prompts et le suivi, activez-le, lancez un premier run et attendez l’événement de webhook run.completed.

Configurez le workspace d’un nouveau client depuis votre propre système, d’un workspace vide jusqu’à un premier run, avec l’API REST. Le workspace reste en `DRAFT` pendant que vous le configurez : rien n’est suivi ni facturé tant que vous ne l’avez pas activé et lancé un run.

## Avant de commencer

* Une offre Business, Agency Business ou Enterprise, et un jeton d’API dont l’accès en écriture a été activé par un Propriétaire ou un Manager. Consultez [Écrire des données](https://docs.qwairy.co/fr/developers/writing-data.md).
* Un endpoint HTTPS public si vous voulez recevoir l’événement `run.completed`. Sinon, interrogez le run.
* Assez de crédits pour le premier run. Vérifiez avec [Crédits](https://docs.qwairy.co/fr/developers/endpoints/credits.md).

Toutes les valeurs ci-dessous sont synthétiques. Chaque `POST` exige un `Idempotency-Key` unique, et chaque `PATCH` exige `If-Match` avec l’`ETag` que vous avez lu en dernier.

## Étapes

**1. Créer le workspace en DRAFT**

```bash theme={null}
curl -i -X POST "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-create" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Analytics", "domain": "acme.example", "countryCode": "US", "languageCode": "EN"}'
```

Conservez `workspace.id` comme `BRAND_ID`. Le workspace est en `DRAFT`, et l’en-tête `ETag` porte sa version.

**2. Créer des Topics et des Tags**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/keywords" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-topic-crm" \
  -H "Content-Type: application/json" \
  -d '{"text": "CRM software"}'

curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/tags" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-tag-pricing" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pricing", "color": "#7B3AEE"}'
```

Conservez `topic.id` comme `TOPIC_ID` et `tag.id` comme `TAG_ID`. Consultez [Créer un Topic](https://docs.qwairy.co/fr/developers/endpoints/keywords/manage.md) et [Créer un Tag](https://docs.qwairy.co/fr/developers/endpoints/tags/create.md).

**3. Créer des prompts**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/prompts" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-prompt-001" \
  -H "Content-Type: application/json" \
  -d '{"text": "Which CRM tools support small sales teams?", "frequency": "WEEKLY", "keywordId": "'"$TOPIC_ID"'", "tagIds": ["'"$TAG_ID"'"]}'
```

Créez un prompt par requête. Les prompts suivis ajoutent une consommation récurrente de crédits. Consultez [Créer un prompt](https://docs.qwairy.co/fr/developers/endpoints/prompts/manage.md).

**4. Configurer le suivi**

Lisez [Obtenir le suivi](https://docs.qwairy.co/fr/developers/endpoints/brands/monitoring.md) pour connaître les modèles sélectionnés et l’`ETag`. Prévisualisez le changement avec `dryRun`, puis enregistrez-le. Quand aucun réglage n’existe encore, le premier `ETag` est `"0"`.

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID/monitoring" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "0"' \
  -H "Content-Type: application/json" \
  -d '{"frequency": "WEEKLY", "analysisWeekDay": 2, "dryRun": true}'
```

Répétez la requête sans `dryRun` pour enregistrer. Consultez [Mettre à jour le suivi](https://docs.qwairy.co/fr/developers/endpoints/brands/update-monitoring.md).

**5. S’abonner à run.completed**

Créez un endpoint de [webhook d’intégration](https://docs.qwairy.co/fr/developers/integration-webhooks/overview.md) limité au nouveau workspace. Conservez le `secret` renvoyé : il n’est affiché qu’une fois.

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/webhooks" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-webhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/qwairy", "events": ["run.completed", "run.failed"], "brandIds": ["'"$BRAND_ID"'"]}'
```

Vérifiez chaque envoi avec [Vérifier les signatures](https://docs.qwairy.co/fr/developers/integration-webhooks/verify-signatures.md).

**6. Activer le workspace**

Relisez le workspace pour obtenir son `ETag` actuel, puis passez-le à `LIVE`. Cet exemple suppose que l’`ETag` lu est `"2"`.

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "2"' \
  -H "Content-Type: application/json" \
  -d '{"status": "LIVE"}'
```

L’activation ne lance jamais de génération. Un workspace au-delà de la limite de l’offre renvoie `409` `QUOTA_EXCEEDED`. Consultez [Mettre à jour un workspace](https://docs.qwairy.co/fr/developers/endpoints/brands/update.md).

**7. Estimer, puis lancer le premier run**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs/estimate" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

curl -i -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-first-run" \
  -H "Content-Type: application/json" -d '{}'
```

Vérifiez `sufficientCredits` dans l’estimation avant de lancer. La requête de lancement renvoie `202` avec un en-tête `Location` et réserve les crédits prévus. Consultez [Estimer un run](https://docs.qwairy.co/fr/developers/endpoints/runs/estimate.md) et [Lancer un run](https://docs.qwairy.co/fr/developers/endpoints/runs/manage.md).

**8. Attendre run.completed**

Votre endpoint reçoit un événement `run.completed` signé lorsque le run atteint un état final :

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "status": "COMPLETED",
    "counts": { "requested": 40, "completed": 40, "failed": 0, "skipped": 0, "cancelled": 0 }
  }
}
```

Dédupliquez sur `id` : la livraison se fait au moins une fois. Un statut `COMPLETED_WITH_WARNINGS` signifie que certaines réponses ont échoué ; lisez donc `counts`. Sans webhook, interrogez [Lister les runs](https://docs.qwairy.co/fr/developers/endpoints/runs/list.md).

## Vérifier le résultat

* [Obtenir le suivi](https://docs.qwairy.co/fr/developers/endpoints/brands/monitoring.md) renvoie le calendrier et les modèles enregistrés.
* [Lister les prompts](https://docs.qwairy.co/fr/developers/endpoints/prompts/list.md) avec `view=configuration` renvoie les prompts, leurs Topics et leurs Tags.
* [Crédits](https://docs.qwairy.co/fr/developers/endpoints/credits.md) montre ce que le run a réservé.

## Limites et retour en arrière

* Rejouer une requête avec le même `Idempotency-Key` et le même corps renvoie la réponse d’origine pendant 24 heures. Utilisez une nouvelle clé pour une nouvelle opération logique, et lisez d’abord l’état après un résultat incertain.
* `412` signifie que la ressource a changé depuis votre lecture. Relisez-la et réappliquez votre modification.
* Un workspace `LIVE` ne peut pas revenir à `DRAFT`. Archivez-le avec `status: ARCHIVED` si le client part.
* Il n’existe pas d’annulation de run dans l’API v1.

## Voir aussi

* [Écrire des données](https://docs.qwairy.co/fr/developers/writing-data.md)
* [Événements des webhooks d’intégration](https://docs.qwairy.co/fr/developers/integration-webhooks/events.md)
* [Outil d’écriture des runs](https://docs.qwairy.co/fr/mcp/write/runs.md) pour l’équivalent MCP du premier run.


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