Help Center API

Categories

JSON Format

Categories have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating categories
name string no yes The name of the category
description string no no The description of the category
locale string no yes The locale that the category is displayed in
source_locale string yes no The source (default) locale of the category
url string yes no The API url of this category
html_url string yes no The url of this category in Help Center
outdated boolean yes no Whether the category is out of date
position integer no no The position of this category relative to other categories
created_at timestamp yes no The time at which the category was created
updated_at timestamp yes no The time at which the category was last updated
Example
 
{
  "id":            1635,
  "name":          "Self Help Articles",
  "description":   "",
  "locale":        "en-us",
  "source_locale": "en-us",
  "url":           "https://company.zendesk.com/api/v2/help_center/categories/354362577",
  "html_url":      "https://company.zendesk.com/hc/en-us/categories/354362577",
  ...
}

List Categories
  • GET /api/v2/help_center/{locale}/categories.json

The {locale} is required only for end users and anonymous users. Admins and agents can omit it.

Allowed for
  • Agents
  • End users
  • Anonymous users

The response will list only the categories that the agent, end user, or anonymous user can view in Help Center.

Sorting

You can sort the results with the sort_by and sort_order query string parameters.

GET /api/v2/help_center/en-us/categories.json?sort_by=updated_at&sort_order=asc

The sort_by parameter can have one of the following values:

value description
position order set manually using the Arrange Content page. Default order
created_at order by creation time
updated_at order by update time

The sort_order parameter can have one of the following values:

value description
asc ascending order
desc descending order
Sideloads

The following sideloads are supported:

Name Will sideload
translations the category translations, if any

Translations are embedded within the category because they're not shared between resources.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/categories.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "categories": [
    {
      "id":          37486578,
      "name":        "Super Hero Tricks",
      "description": "This category contains a collection of Super Hero tricks",
      "locale":      "en-us",
      ...
    },
      "id":          354675463,
      "name":        "Tips & Tricks",
      "description": "All the cool tricks!",
      "locale":      "en-us",
      ...
    },
    ...
  ]
}

Show Category
  • GET /api/v2/help_center/{locale}/categories/{id}.json

The {locale} is required only for end users and anonymous users. Admins and agents can omit it.

Allowed for
  • Agents
  • End users
  • Anonymous users
Sideloads

The following sideloads are supported:

Name Will sideload
translations the category translations, if any

Translations are embedded within the category because they're not shared between resources.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/categories/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "category": {
    "id":          354675467,
    "name":        "Tips & Tricks",
    "description": "All the cool tricks!",
    "locale":      "en-us",
  }
}

Create Category
  1. POST /api/v2/help_center/categories.json
  2. POST /api/v2/help_center/{locale}/categories.json

You must specify a category name and locale. The locale can be omitted if it's specified in the URL. Optionally, you can specify multiple translations for the category. The specified locales must be enabled for the current Help Center.

Allowed for
  • Help Center managers
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories.json \
  -d '{"category": {"position": 2, "locale": "en-us", "name":  "Super Hero Tricks",\
    "description": "This category contains a collection of super hero tricks"}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

You can also specify multiple translations for the new category:

curl https://{subdomain}.zendesk.com/api/v2/help_center/categories.json \
  -d '{"category": {"position": 2, "translations":  \
    [{"locale": "en-us", "title": "Super Hero Tricks", \
    "body": "This category contains a collection of Super Hero tricks"},  \
    {"locale": "fr", "title": "Trucs Super Heros", \
    "body": "Cette categorie contient une collection de trucs super heros"}]}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
Example Response
 
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/help_center/categories/{id}.json

{
  "category": {
    "id":          37486578,
    "name":        "Super Hero Tricks",
    "description": "This category contains a collection of Super Hero tricks",
    "locale":      "en-us",
    "position":    2,
    ...
  }
}

Update Category
  1. PUT /api/v2/help_center/categories/{id}.json
  2. PUT /api/v2/help_center/{locale}/categories/{id}.json

These endpoints only update category-level metadata such as the sorting position. They don't update category translations.

Allowed for
  • Help Center managers
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{id}.json \
  -d '{"category": {"position": 2}}' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
 
Status: 200 OK

{
  "category": {
    "id":              37486578,
    "position":        42,
    ...
  }
}

Update Category source locale

PUT /api/v2/help_center/categories/{id}/source_locale.json

The endpoint updates category source_locale property

Allowed for
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{id}/source_locale.json \
  -d '{"category_locale": "fr"}' -v -u {email_address}:{password} -X PUT \
  -H "Content-Type: application/json"
Example Response
 
Status: 200 OK

Delete Category

DELETE /api/v2/help_center/categories/{id}.json

WARNING: Every section and all articles in the category will also be deleted.

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