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

# Générer des suggestions de prompts

> Lancez une génération Prompt Studio pour un workspace ou un Topic. Elle ne consomme aucun crédit client, renvoie 202 et est limitée par workspace sur 24 heures.

Lance une génération de Prompt Studio. La requête renvoie `202` avec la génération et un en-tête `Location`. Interrogez [Obtenir une génération de suggestions](https://docs.qwairy.co/fr/developers/endpoints/prompt-suggestions/get-run.md), ou abonnez un [webhook d’intégration](https://docs.qwairy.co/fr/developers/integration-webhooks/overview.md) à [`prompt_suggestions.ready`](https://docs.qwairy.co/fr/developers/integration-webhooks/events#prompt_suggestions-ready) et [`prompt_suggestions.failed`](https://docs.qwairy.co/fr/developers/integration-webhooks/events#prompt_suggestions-failed).

La génération ne consomme aucun crédit client. Elle est limitée à 3 générations de workspace et 10 générations de Topic par workspace sur 24 heures glissantes. Une génération de workspace et une génération par Topic peuvent être en cours simultanément. Une requête portant sur le même périmètre déjà en cours renvoie `409 RESOURCE_BUSY`.

Nécessite une offre Business, Agency Business ou Enterprise active, 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) pour l’activation, l’idempotence, les requêtes conditionnelles et la gestion des erreurs.

**Authorization** `string` *required*

Jeton bearer de votre équipe.

**Idempotency-Key** `string` *required*

Clé unique pour cette opération, 255 caractères au maximum. Les réponses terminées sont rejouées pendant 24 heures.

**brandId** `string` *required*

Identifiant du workspace. Le workspace doit appartenir à l’équipe du jeton.

**source** `string` (default: manual)

`manual` pour tout le workspace, ou `topic` pour un seul Topic.

**keywordId** `string`

Identifiant du Topic. Obligatoire lorsque `source` vaut `topic`.

**refill** `boolean` (default: false)

Ajoute des suggestions au lot actuel au lieu de repartir de zéro.

## Réponse

Renvoie `202` avec la génération.

**id** `string`

Identifiant de la génération

**status** `string`

`PENDING`, `RUNNING`, `COMPLETED` ou `FAILED`

**source** `string`

`manual`, `onboarding`, `topic` ou `profile`

**keywordId** `string | null`

Topic ciblé par la génération, lorsque `source` vaut `topic`

**recommendations** `integer | null`

Nombre de suggestions recommandées, une fois connu

**createdAt** `string`

Date de création au format ISO 8601

**completedAt** `string | null`

Date de fin au format ISO 8601, ou `null` tant que la génération est en cours

## Requête et réponse synthétiques

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

```json theme={null}
{
  "id": "bbbbbbbb-0000-4000-8000-000000000000",
  "status": "PENDING",
  "source": "manual",
  "keywordId": null,
  "recommendations": null,
  "createdAt": "2026-10-12T09:00:00.000Z",
  "completedAt": null
}
```

## Erreurs

| Statut | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | `keywordId` est absent avec `source: topic`, ou une valeur est invalide |
| `404` | `RESOURCE_NOT_FOUND` | Le workspace ou le Topic est absent ou inaccessible |
| `409` | `RESOURCE_BUSY` | Une génération est en cours pour ce périmètre ; `error.details.suggestionRunId` l’identifie |
| `409` | `QUOTA_EXCEEDED` | Le quota glissant est épuisé ; `error.details.resetsAt` indique sa réinitialisation lorsqu’elle est connue |
| `409` | `CONFLICT` | Un Topic nécessite un lot existant, ou aucun Topic suivi n’a besoin de nouvelles suggestions |

Consultez [Codes d’erreur](https://docs.qwairy.co/fr/developers/errors.md) pour les erreurs d’authentification, d’offre, d’idempotence et de serveur. Un jeton sans accès en écriture renvoie `403 API_KEY_READ_ONLY`. Sur `429`, respectez `Retry-After`. Si le limiteur d’écriture est indisponible ou si les écritures sont suspendues, la requête renvoie `503 SERVICE_UNAVAILABLE` et rien ne change.


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