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

# Generate prompt suggestions

> Start a Prompt Studio generation for a workspace or one topic. It uses no customer credits, returns 202, and is limited per workspace over 24 hours.

Starts a Prompt Studio generation. The request returns `202` with the generation
and a `Location` header. Poll [Get a suggestion generation](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/get-run.md),
or subscribe an [integration webhook](https://docs.qwairy.co/developers/integration-webhooks/overview.md) to
[`prompt_suggestions.ready`](https://docs.qwairy.co/developers/integration-webhooks/events#prompt_suggestions-ready) and
[`prompt_suggestions.failed`](https://docs.qwairy.co/developers/integration-webhooks/events#prompt_suggestions-failed).

Generation uses no customer credits. It is limited to 3 workspace generations
and 10 topic generations per workspace over a rolling 24 hours. At most one
workspace generation and one generation per topic can run at a time. A request
for the same running scope returns `409 RESOURCE_BUSY`.

Requires an active Business, Agency Business or Enterprise plan, and an API token with write access enabled by an Owner or Manager. See [Writing data](https://docs.qwairy.co/developers/writing-data.md) for activation, idempotency, conditional requests and error handling.

**Authorization** `string` *required*

Bearer token for your team.

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

Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

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

`manual` for the whole workspace, or `topic` for one topic.

**keywordId** `string`

Topic identifier. Required when `source` is `topic`.

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

Add suggestions to the current pool instead of starting over.

## Response

Returns `202` with the generation.

**id** `string`

Generation identifier

**status** `string`

`PENDING`, `RUNNING`, `COMPLETED` or `FAILED`

**source** `string`

`manual`, `onboarding`, `topic` or `profile`

**keywordId** `string | null`

Topic the generation targeted, when `source` is `topic`

**recommendations** `integer | null`

Number of recommended suggestions, once known

**createdAt** `string`

ISO 8601 creation time

**completedAt** `string | null`

ISO 8601 completion time, or `null` while the generation is in progress

## Synthetic request and response

```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
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | `keywordId` is missing with `source: topic`, or a value is invalid |
| `404` | `RESOURCE_NOT_FOUND` | The workspace or topic is missing or inaccessible |
| `409` | `RESOURCE_BUSY` | A generation for this scope is running; `error.details.suggestionRunId` identifies it |
| `409` | `QUOTA_EXCEEDED` | The rolling allowance is exhausted; `error.details.resetsAt` gives the reset when known |
| `409` | `CONFLICT` | A topic needs an existing pool, or no monitored topic needs a refill |

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency and server errors. A token without write access returns `403 API_KEY_READ_ONLY`. On `429`, honor `Retry-After`. If the write limiter is unavailable or writes are suspended, the request returns `503 SERVICE_UNAVAILABLE` and nothing changes.


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