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

> Create a topic label to organize prompts in a workspace. The API path keeps the name keywords; assign the topic to prompts with a prompt update.

Creates a topic label. The API path keeps the name `keywords`; the resource
is a topic. Use [Update a prompt](https://docs.qwairy.co/developers/endpoints/prompts/update.md) to assign it.

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*

Topic text, 1 to 255 characters after trimming.

## Response

Returns `201` with `Location`, `ETag` and a `topic` containing
`id`, `text`, `version`, `createdAt` and `updatedAt`.

## Synthetic request and response

```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: topic-pricing-001" \
  -H "Content-Type: application/json" \
  -d '{"text":"Pricing"}'
```

```json theme={null}
{
  "topic":{
    "id":"11111111-0000-4000-8000-000000000000",
    "text":"Pricing",
    "version":0,
    "createdAt":"2026-09-01T09:00:00.000Z",
    "updatedAt":"2026-09-01T09:00:00.000Z"
  }
}
```

## Related operations

* [Get a topic](https://docs.qwairy.co/developers/endpoints/keywords/get.md), [update it](https://docs.qwairy.co/developers/endpoints/keywords/update.md)
  or [delete it](https://docs.qwairy.co/developers/endpoints/keywords/delete.md).
* [List topics](https://docs.qwairy.co/developers/endpoints/keywords/list.md) with `view=configuration`
  to include labels without answers and their current versions.
* [Create a tag](https://docs.qwairy.co/developers/endpoints/tags/create.md) for reusable secondary labels.

## Errors

Invalid text returns `400 INVALID_REQUEST`; an inaccessible workspace returns
`404 RESOURCE_NOT_FOUND`; a duplicate label returns `409 CONFLICT`.

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.