Skip to main content
POST
Create a prompt
Creates a prompt without starting billable answer collection. Use Start a run 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 for idempotency, conditional requests and error handling.
string
required
Bearer token for your team.
string
required
Unique key for this operation. Completed responses replay for 24 hours.
string
required
Workspace identifier. The workspace must belong to the token’s team.
string
required
Prompt text, 1 to 500 characters after trimming, as in the dashboard.
string | null
NONE, DAILY, WEEKLY, MONTHLY, or null. Omit or use null to inherit the workspace schedule.
string | null
Topic UUID from this workspace. Omit or use null to create an unassigned prompt.
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.
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.
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

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 for authentication, plan, idempotency and server errors. On 429, honor Retry-After; writes can return 503 SERVICE_UNAVAILABLE if the write limiter is unavailable.