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

# Create a prompt

> Add a monitored prompt with an optional schedule, topic, tags, countries and models. Creating a prompt does not start billable answer collection.

Creates a prompt without starting billable answer collection.
Use [Start a run](https://docs.qwairy.co/developers/endpoints/runs/manage.md) to request fresh answers
for a live workspace.

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

**Authorization** `string` *required*

Bearer token for your team.

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

Unique key for this operation. Completed responses replay for 24 hours.

**brandId** `string` *required*

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

**text** `string` *required*

Prompt text, 1 to 500 characters after trimming, as in the dashboard.

**frequency** `string | null`

`NONE`, `DAILY`, `WEEKLY`, `MONTHLY`, or null. Omit or use null to
inherit the workspace schedule.

**keywordId** `string | null`

Topic UUID from this workspace. Omit or use null to create an unassigned prompt.

**tagIds** `string[]`

Up to 50 tag UUIDs from this workspace. Defaults to no tags. In a workspace created from v1.21,
Qwairy sets the `Branded` or `Non-branded` system tag from the prompt text.
The id of either system tag is ignored if you send it.

**countryCodes** `string[]`

Up to 50 uppercase two-letter country codes from the workspace country
catalog, the countries this prompt runs in. Omit it or send an empty array to
use the workspace default country. Manage the catalog with
[Update a workspace](https://docs.qwairy.co/developers/endpoints/brands/update.md).

**modelIds** `string[]`

Up to 30 model identifiers for this prompt only. Omit it or send an empty
array to use the workspace models.

## Response

Returns `201` with `Location`, `ETag` and a `prompt` containing `id`,
`text`, `status`, nullable `frequency`, `monitoringEnabled`, nullable
`keywordId`, `tagIds`, `countryCodes`, `modelIds`, `version`, `createdAt`
and `updatedAt`. A new prompt has `status: ACTIVE`. In a workspace created from v1.21 it also carries one system tag, so `tagIds`
includes its id; a workspace created earlier has no system tags. `countryCodes` and
`modelIds` echo what the prompt stores: an empty array means the prompt uses
the workspace default country or models.

## Synthetic request and response

```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: prompt-crm-001" \
  -H "Content-Type: application/json" \
  -d '{"text":"Which CRM tools support small sales teams?","frequency":"WEEKLY"}'
```

```json theme={null}
{
  "prompt":{
    "id":"33333333-0000-4000-8000-000000000000",
    "text":"Which CRM tools support small sales teams?",
    "status":"ACTIVE",
    "frequency":"WEEKLY",
    "monitoringEnabled":true,
    "keywordId":null,
    "tagIds":["55555555-0000-4000-8000-000000000000"],
    "countryCodes":[],
    "modelIds":[],
    "version":0,
    "createdAt":"2026-09-01T09:00:00.000Z",
    "updatedAt":"2026-09-01T09:00:00.000Z"
  }
}
```

## Related operations

* [Update, archive or restore a prompt](https://docs.qwairy.co/developers/endpoints/prompts/update.md).
* [Bulk update prompts](https://docs.qwairy.co/developers/endpoints/prompts/bulk.md).
* [List prompts](https://docs.qwairy.co/developers/endpoints/prompts/list.md) with `view=configuration`
  to retrieve editable fields and archived prompts.

## Errors

Invalid fields return `400 INVALID_REQUEST`; inaccessible workspace or label
IDs return `404 RESOURCE_NOT_FOUND`. Duplicate text, including an archived
prompt with the same text, returns `409 CONFLICT`; restore the archived prompt
instead of recreating it.

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency
and server errors. On `429`, honor `Retry-After`; writes can return
`503 SERVICE_UNAVAILABLE` if the write limiter is unavailable.


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