Topics

A topic represents a collection of community posts on a subject.

JSON Format

Topics have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the topic is created
url string yes no The API url of the topic
html_url string yes no The community url of the topic
name string no yes The name of the topic
description string no no The description of the topic. By default an empty string
position integer no no The position of the topic relative to other topics in the community
follower_count integer yes no The number of users following the topic
manageable_by string no no The set of users who can manage this topic
user_segment_id integer no no The id of the user segment to which this topic belongs
created_at timestamp yes no When the topic was created
updated_at timestamp yes no When the topic was last updated

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
{
  "id":             1635,
  "name":           "Security",
  "description":    "Security Best Practices",
  "follower_count": 332,
  "manageable_by":  "staff",
  "created_at":     "2012-04-04T09:14:57Z",
  ...
}

List Topics

GET /api/v2/community/topics.json

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": [
    {
      "id": 10,
      "url": "https://{subdomain}.zendesk.com/api/v2/community/topics/10.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en-us/community/topics/10-Using-Help-Center-Tips-Tricks",
      "name": "Using Help Center - Tips & Tricks",
      ...
    },
    {
      "id": 11,
      "url": "https://{subdomain}.zendesk.com/api/v2/community/topics/11.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en-us/community/topics/11-Using-Help-Center-Getting-Started-Guide",
      "name": "Using Help Center - Getting Started Guide",
      ...
    },
    ...
   ]
}

Show Topic

GET /api/v2/community/topics/{id}.json

Shows information about a single topic.

Allowed for
  • Agents
  • End users
  • Anonymous users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "topic": {
    "id":          35467,
    "name":        "Security",
    "description": "Security Best Practices",
    ...
  }
}

Create Topic

POST /api/v2/community/topics.json

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 OK
Location:
https://{subdomain}.zendesk.com/api/v2/community/topics.json

{
  "topic": {
    "name":        "Help Center-Tricks",
    ...
  }
}

Update Topic

PUT /api/v2/community/topics/{id}.json

Allowed for
  • Help Center managers
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
Location:
https://{subdomain}.zendesk.com/api/v2/community/topics/{id}.json

{
  "topic": {
    "name":        "Help Center-Tricks Updated",
    ...
  }
}

Delete Topic

DELETE /api/v2/community/topics/{id}.json

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content