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