Topics
A topic represents a collection of community posts on a subject.
JSON Format
Topics are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | When the topic was created |
description | string | false | false | The description of the topic. By default an empty string |
follower_count | integer | true | false | The number of users following the topic |
html_url | string | true | false | The community url of the topic |
id | integer | true | false | Automatically assigned when the topic is created |
manageable_by | string | false | false | The set of users who can manage this topic. Allowed values are "staff", or "managers". |
name | string | false | true | The name of the topic |
position | integer | false | false | The position of the topic relative to other topics in the community |
updated_at | string | true | false | When the topic was last updated |
url | string | true | false | The API url of the topic |
user_segment_id | integer | false | false | The id of the user segment to which this topic belongs |
The manageable_by
attribute takes one of the following values:
Value | Users |
---|---|
staff | agents and managers |
managers | only Help Center managers |
Note that manageable_by
is only displayed to users who can manage the topic.
Example
{
"created_at": "2012-04-04T09:14:57Z",
"description": "Security Best Practices",
"follower_count": 332,
"id": 1635,
"manageable_by": "staff",
"name": "Security"
}
List Topics
GET /api/v2/community/topics
Lists all topics.
Allowed for
- Agents
- End users
- Anonymous users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"topics": [
{
"html_url": "https://{subdomain}.zendesk.com/hc/en-us/community/topics/10-Using-Help-Center-Tips-Tricks",
"id": 10,
"name": "Using Help Center - Tips \u0026 Tricks",
"url": "https://{subdomain}.zendesk.com/api/v2/community/topics/10.json"
},
{
"html_url": "https://{subdomain}.zendesk.com/hc/en-us/community/topics/11-Using-Help-Center-Getting-Started-Guide",
"id": 11,
"name": "Using Help Center - Getting Started Guide",
"url": "https://{subdomain}.zendesk.com/api/v2/community/topics/11.json"
}
]
}
Create Topic
POST /api/v2/community/topics
Allowed for
- Help Center managers
Agents with the Help Center Manager role can optionally supply a created_at
as part of the topic
object. If it is not provided created_at
is set to the current time.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics.json \
-v -u {email_address}:{password} -d '{"topic": {"name": "Help Center-Tricks"}}' \
-X POST -H "Content-Type: application/json"
Example Response
Status 201 Created
{
"topic": {
"description": "Security Best Practices",
"id": 35467,
"name": "Help Center-Tricks"
}
}
Show Topic
GET /api/v2/community/topics/{topic_id}
Shows information about a single topic.
Allowed for
- Agents
- End users
- Anonymous users
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
topic_id | integer | Path | true | The unique ID of this Topic |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"topic": {
"description": "Security Best Practices",
"id": 35467,
"name": "Help Center-Tricks"
}
}
Update Topic
PUT /api/v2/community/topics/{topic_id}
Allowed for
- Help Center managers
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
topic_id | integer | Path | true | The unique ID of this Topic |
Using curl
curl -v -u {email_address}:{password} -d '{"topic": {"name": "Help Center-Tricks Updated"}}' \
-X PUT -H "Content-Type: application/json"
Example Response
Status 200 OK
{
"topic": {
"description": "Security Best Practices",
"id": 35467,
"name": "Help Center-Tricks"
}
}
Delete Topic
DELETE /api/v2/community/topics/{topic_id}
Allowed for
- Help Center managers
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
topic_id | integer | Path | true | The unique ID of this Topic |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}.json \
-v -u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content