---
title: "Create a topic"
method: POST
path: "/v2/topics"
tags: ["Topics (group chats/channels/conversations)"]
---

# Create a topic

`POST /v2/topics`

## Request

- Base URL: `https://api.zenzap.co`
- URL: `https://api.zenzap.co/v2/topics`
- Auth: one of:
  - HTTP bearer and API key in header `X-Signature`
  - OAuth 2
    - Client credentials
    - Token URL: `https://api.zenzap.co/oauth/token` scopes: `channel:write`
- TypeScript: <https://skmtc.dev/zenzap/apis/zenzap-external-integration-api/docs/v2/topics/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new topic with specified members. Your API key bot will automatically be added as a member.

Supported request modes:
- `application/json` — create a topic without a cover image
- `multipart/form-data` — create a topic with an optional cover image. Send a `metaPart`
  (JSON topic fields, same shape as the JSON body) and an optional `filePart` (the cover
  image). The image is validated first: an invalid or oversized image returns 400 and no
  topic is created (see requirements below). A valid cover is then applied to the topic
  (non-square images are center-cropped); if that upload step fails afterwards the topic is
  still created, just without a cover.

Cover image requirements (when `filePart` is provided):
- must be a valid image (JPEG or PNG)
- non-square images are automatically center-cropped to a square
- max dimension 4096×4096; larger images return 400
- max size 8 MB; converted to JPEG automatically

Limits:
- topic name is limited to 64 characters
- topic description is limited to 10000 characters
- maximum 100 members per topic
- you can only add members that are already in your organization
- topic externalId is limited to 100 characters
- externalId must be unique per bot - you cannot create multiple topics with the same externalId

## Headers

- `X-Signature` string
- `X-Timestamp` integer

## Request body

- TopicCreateRequest
  - `name` string, required: The topic name
  - `description` string: Optional topic description
  - `members` string[], required: Array of user IDs to add as topic members (max 100). Your bot will automatically be added as a member.
  - `externalId` string: Optional external identifier for tracking purposes. Must be unique per bot - you cannot reuse the same external ID for multiple topics.

## Response `201`

Topic created successfully

- TopicCreateResponse
  - `id` string, uuid: The created topic ID
  - `name` string: The topic name
  - `members` string[]: Array of member IDs in the topic (including the bot)
  - `externalId` string: The fully qualified external ID (bot_id:your_external_id). Only present if externalId was provided in the request.
  - `createdAt` integer: Unix timestamp in milliseconds

## Other responses

- `400`: Bad request - invalid input
- `401`: Unauthorized - invalid or missing API token
- `500`: Internal server error

---

[API](https://skmtc.dev/zenzap/apis/zenzap-external-integration-api.md) - [All operations](https://skmtc.dev/zenzap/apis/zenzap-external-integration-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zenzap/apis/zenzap-external-integration-api/revisions/37faae2c2036?raw)