Categories

JSON Format

Categories are represented as JSON objects with the following properties:

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

List Categories

  • GET /api/v2/help_center{/locale}/categories

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

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.

Parameters
Name Type In Required Description
sort_by string Query false Sorts the results by one of the accepted values. Allowed values are "position", "created_at", or "updated_at".
sort_order string Query false Selects the order of the results. Allowed values are "asc", or "desc".
locale string Path false The locale that the category is displayed in
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": [
    {
      "description": "This category contains a collection of Super Hero tricks",
      "id": 37486578,
      "locale": "en-us",
      "name": "Super Hero Tricks"
    },
    {
      "description": "All the cool tricks!",
      "id": 354675463,
      "locale": "en-us",
      "name": "Tips \u0026 Tricks"
    }
  ]
}

Create Category

  • POST /api/v2/help_center{/locale}/categories

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
Parameters
Name Type In Required Description
locale string Path false The locale that the category is displayed in
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"
Using curl
# 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

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

Show Category

  • GET /api/v2/help_center{/locale}/categories/{category_id}

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

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.

Parameters
Name Type In Required Description
category_id integer Path true The unique ID of this Category
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/categories/{category_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

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

Update Category

  • PUT /api/v2/help_center{/locale}/categories/{category_id}

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

Allowed for
  • Help Center managers
Parameters
Name Type In Required Description
category_id integer Path true The unique ID of this Category
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}.json \
-d '{"category": {"position": 2}}' \
-v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
Status 200 OK

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

Delete Category

  • DELETE /api/v2/help_center{/locale}/categories/{category_id}

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

Allowed for
  • Help Center managers
Parameters
Name Type In Required Description
category_id integer Path true The unique ID of this Category
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content

Update Category Source Locale

  • PUT /api/v2/help_center{/locale}/categories/{category_id}/source_locale

The endpoint updates the category source_locale property

Allowed for
  • Agents
Parameters
Name Type In Required Description
category_id integer Path true The unique ID of this Category
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_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