Categories are the top-level organizing containers of the knowledge base in the help center. Categories contain related sections. See Organizing knowledge base content in categories and sections in Zendesk help.

JSON format

Categories are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringtruefalseThe time at which the category was created
descriptionstringfalsefalseThe description of the category
html_urlstringtruefalseThe url of this category in Help Center
idintegertruetrueAutomatically assigned when creating categories
localestringfalsetrueThe locale where the category is displayed
namestringfalsetrueThe name of the category
outdatedbooleantruefalseWhether the category is out of date
positionintegerfalsefalseThe position of this category relative to other categories
source_localestringtruefalseThe source (default) locale of the category
updated_atstringtruefalseThe time at which the category was last updated
urlstringtruefalseThe 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
  • GET /api/v2/help_center/categories

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

Allowed for

  • Anonymous users

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

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

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:

valuedescription
positionorder set manually using the Arrange Content page. Default order
created_atorder by creation time
updated_atorder by update time

The sort_order parameter can have one of the following values:

valuedescription
ascascending order
descdescending order

Sideloads

The following sideloads are supported:

NameWill sideload
translationsthe category translations, if any

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

Parameters

NameTypeInRequiredDescription
sort_bystringQueryfalseSorts the results by one of the accepted values. Allowed values are "position", "created_at", or "updated_at".
sort_orderstringQueryfalseSelects the order of the results. Allowed values are "asc", or "desc".
localestringPathtrueThe locale the item is displayed in

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/categories.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories?sort_by=&sort_order="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories")		.newBuilder()		.addQueryParameter("sort_by", "")		.addQueryParameter("sort_order", "");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'sort_by': '',    'sort_order': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories?sort_by=&sort_order="headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories")uri.query = URI.encode_www_form("sort_by": "", "sort_order": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 & Tricks"    }  ]}

Show Category

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

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

Allowed for

  • Anonymous users

Sideloads

The following sideloads are supported:

NameWill sideload
translationsthe category translations, if any

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

Parameters

NameTypeInRequiredDescription
category_idintegerPathtrueThe unique ID of the category
localestringPathtrueThe locale the item is displayed in

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/categories/{category_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

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

Create Category

  • POST /api/v2/help_center/{locale}/categories
  • POST /api/v2/help_center/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

NameTypeInRequiredDescription
localestringPathtrueThe locale the item is displayed in

Code Samples

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}/token:{api_token} -X POST -H "Content-Type: application/json"
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}/token:{api_token} -X POST -H "Content-Type: application/json"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"POST",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// Status 201 Created
{  "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}
  • PUT /api/v2/help_center/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

NameTypeInRequiredDescription
category_idintegerPathtrueThe unique ID of the category
localestringPathtrueThe locale the item is displayed in

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}.json \-d '{"category": {"position": 2}}' \-v -u {email_address}/token:{api_token} -X PUT -H "Content-Type: application/json"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"PUT",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 Source Locale

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

The endpoint updates the category source_locale property

Allowed for

  • Agents

Parameters

NameTypeInRequiredDescription
category_idintegerPathtrueThe unique ID of the category
localestringPathtrueThe locale the item is displayed in

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}/source_locale.json \-d '{"category_locale": "fr"}' -v -u {email_address}/token:{api_token} -X PUT \-H "Content-Type: application/json"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/source_locale"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/source_locale")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/source_locale',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/source_locale"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"PUT",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/source_locale")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
null

Delete Category

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

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

Allowed for

  • Help Center managers

Parameters

NameTypeInRequiredDescription
category_idintegerPathtrueThe unique ID of the category
localestringPathtrueThe locale the item is displayed in

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}.json \  -v -u {email_address}/token:{api_token} -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"DELETE",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

204 No Content
// Status 204 No Content
null