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