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