Docs
kirora.ioGet started
Topics overviewMenu
On this page

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

EndpointRequest
List topicsGET /v1/topics
Create a topicPOST /v1/topics
Retrieve a topicGET /v1/topics/{id}
Update a topicPATCH /v1/topics/{id}
Delete a topicDELETE /v1/topics/{id}

The Topic object

Topic example
{
  "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
  }
}
idstringrequired

uuid

namestringrequired
descriptionstring | nullrequired
modestringrequired

opt_out reaches everyone who has not left; opt_in only those who joined.

one of opt_out, opt_in

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

countsobjectrequired

Counted now, as the topic rule without channel reads it; a contact's channel choice can still differ on that channel.

2 child attributes
inintegerrequired

Contacts the topic reaches topic-wide: for opt_out everyone who has not left, for opt_in those who joined.

min 0

leftintegerrequired

Contacts who left the topic.

min 0