# Topics

Source: https://kirora.io/docs/api/reference/topics

A topic is a kind of marketing a contact can choose, such as product updates, and a topic choice is their choice for it on every channel or one. Topic choice works on top of consent, not instead of it: a send on a topic needs consent on the channel and the topic reaching the contact. An `opt_out` topic reaches everyone with consent who has not left it; an `opt_in` topic only those who joined. A contact's topic choices: `GET /v1/contacts/{id}/topics`.

## Endpoints

- [List topics](https://kirora.io/docs/api/reference/listTopics): `GET /v1/topics`
- [Create a topic](https://kirora.io/docs/api/reference/createTopic): `POST /v1/topics`
- [Retrieve a topic](https://kirora.io/docs/api/reference/getTopic): `GET /v1/topics/{id}`
- [Update a topic](https://kirora.io/docs/api/reference/updateTopic): `PATCH /v1/topics/{id}`
- [Delete a topic](https://kirora.io/docs/api/reference/deleteTopic): `DELETE /v1/topics/{id}`

## The Topic object

```json
{
  "id": "0192f3b0-6a1b-7c2d-8e3f-4a5b6c7d8e9f",
  "name": "Weekly offers",
  "description": "Discounts and bundles, once a week",
  "mode": "opt_out",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-09-01T10:00:00.000Z",
  "counts": {
    "in": 11842,
    "left": 316
  }
}
```

- `id` (string, required, uuid)
- `name` (string, required)
- `description` (string | null, required)
- `mode` (string, required, one of `opt_out`, `opt_in`) — `opt_out` reaches everyone who has not left; `opt_in` only those who joined.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)
- `counts` (object, required) — Counted now, as the topic rule without `channel` reads it; a contact's channel choice can still differ on that channel.
  - `in` (integer, required, min 0) — Contacts the topic reaches topic-wide: for `opt_out` everyone who has not left, for `opt_in` those who joined.
  - `left` (integer, required, min 0) — Contacts who left the topic.