API reference

Topics API

Reference for creating, listing, retrieving, updating and deleting topics that contacts can opt in to or out of.

The topics API manages the topics of the project that owns your API key. Every endpoint needs a full_access key. For the concepts, see Topics. To set a contact's choice for a topic, see the contacts API.

The topic object

JSON

{
  "object": "topic",
  "id": "jt3b6n9q2w5e8r1y4u7i0o2p",
  "name": "Product updates",
  "description": "New features and improvements",
  "default_subscription": "opt_in",
  "created_at": "2026-11-14T10:00:00.000Z"
}

Create a topic

POST/topics

Field	Type	Required	Description
`name`	string	Yes	1 to 100 characters.
`default_subscription`	string	Yes	`opt_in` or `opt_out`. Applies to contacts who have made no choice. It cannot be changed later.
`description`	string	No	Up to 500 characters. Shown on the preferences page.

Shell

curl -X POST https://api.sooner.dev/topics \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product updates", "description": "New features and improvements", "default_subscription": "opt_in" }'

JSON

{ "id": "jt3b6n9q2w5e8r1y4u7i0o2p" }

List topics

GET/topics

Returns every topic in the project, newest first. The list is not paginated.

Shell

curl https://api.sooner.dev/topics \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "object": "topic",
      "id": "jt3b6n9q2w5e8r1y4u7i0o2p",
      "name": "Product updates",
      "description": "New features and improvements",
      "default_subscription": "opt_in",
      "created_at": "2026-11-14T10:00:00.000Z"
    }
  ],
  "has_more": false
}

Retrieve a topic

GET/topics/{id}

Returns one topic in the shape above. Notable errors: not_found.

Update a topic

PATCH/topics/{id}

Field	Type	Required	Description
`name`	string	No	1 to 100 characters.
`description`	string	No	Up to 500 characters.

Shell

curl -X PATCH https://api.sooner.dev/topics/jt3b6n9q2w5e8r1y4u7i0o2p \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Release notes and new features" }'

JSON

{ "id": "jt3b6n9q2w5e8r1y4u7i0o2p" }

Delete a topic

DELETE/topics/{id}

Deletes the topic and every contact's preference for it. Deletion finishes in the background.

Shell

curl -X DELETE https://api.sooner.dev/topics/jt3b6n9q2w5e8r1y4u7i0o2p \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{ "object": "topic", "id": "jt3b6n9q2w5e8r1y4u7i0o2p", "deleted": true }