Create a topic

Authorizations

Authorization

string

header

required

Bearer token for the request. Two flavors:

Static API key — pass your API key (the value returned as apiKey when the bot was created). Must be paired with X-Signature + X-Timestamp (the hmacSignature scheme).
OAuth access token — pass the JWT returned by POST /oauth/token. No signature headers are required.

X-Signature

string

header

required

HMAC-SHA256 signature for request verification. Required only when authenticating with a static API key. Omit when using an OAuth access token.

Headers

X-Signature

string

HMAC signature of the request for authentication and replay protection.

Required only when authenticating with a static API key. If you are using an OAuth access token (issued by POST /oauth/token), omit this header — the JWT carries all the authentication and integrity guarantees.

Replay Protection: The signature includes a timestamp to prevent replay attacks. Requests with timestamps older than 5 minutes are rejected.

The signature payload differs by HTTP method:

POST/PUT/PATCH/DELETE: HMAC-SHA256 of {timestamp}.{body}
GET: HMAC-SHA256 of {timestamp}.{uri}

The signature is calculated as:

Get the current Unix timestamp in milliseconds
Determine the payload:
- For POST/PUT/PATCH/DELETE: Use {timestamp}.{body} where body is the request body
- For GET: Use {timestamp}.{uri} where uri is the full request URI (e.g., /v2/members?limit=10)
Calculate HMAC-SHA256 of the combined payload using your API secret
Hex-encode the output
Include the timestamp in the X-Timestamp header

Example for GET request to /v2/members?limit=10:

timestamp = 1699564800000
payload = "1699564800000./v2/members?limit=10"
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

Example for POST request with body {"topicId":"123","text":"Hello"}:

timestamp = 1699564800000
payload = '1699564800000.{"topicId":"123","text":"Hello"}'
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

For multipart/form-data requests, sign the exact raw request body bytes (including boundaries and file bytes) as transmitted.

Pattern: ^[a-f0-9]{64}$

Example:

"a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6"

X-Timestamp

integer<int64>

Unix timestamp in milliseconds when the request was created. Used for replay protection — requests older than 5 minutes are rejected.

Required only when authenticating with a static API key. Omit when using an OAuth access token.

Example:

1699564800000

Body

application/json

name

string

required

The topic name

Maximum string length: 64

Example:

"Project Updates"

members

string<uuid>[]

required

Array of user IDs to add as topic members (max 100). Your bot will automatically be added as a member.

Maximum array length: 100

Example:

[
  "550e8400-e29b-41d4-a716-446655440001",
  "550e8400-e29b-41d4-a716-446655440002"
]

description

string

Optional topic description

Maximum string length: 10000

Example:

"Discussion for project milestones"

externalId

string

Optional external identifier for tracking purposes. Must be unique per bot - you cannot reuse the same external ID for multiple topics.

Maximum string length: 100

Example:

"project-alpha"

Response

Topic created successfully

string<uuid>

The created topic ID

name

string

The topic name

members

string[]

Array of member IDs in the topic (including the bot)

Example:

[
  "550e8400-e29b-41d4-a716-446655440001",
  "b@660e8400-e29b-41d4-a716-446655440003"
]

externalId

string

The fully qualified external ID (bot_id:your_external_id). Only present if externalId was provided in the request.

Example:

"b@660e8400-e29b-41d4-a716-446655440003:project-alpha"

createdAt

integer<int64>

Unix timestamp in milliseconds