Sections contain related articles. See Organizing knowledge base content in categories and sections in Zendesk help.

JSON format

Sections are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
category_idintegerfalsefalseThe id of the category to which this section belongs
created_atstringtruefalseThe time at which the section was created
descriptionstringfalsefalseThe description of the section
html_urlstringtruefalseThe url of this section in HC
idintegertruefalseAutomatically assigned when creating subscriptions
localestringfalsetrueThe locale in which the section is displayed
namestringfalsetrueThe name of the section
outdatedbooleantruefalseWhether the section is out of date
parent_section_idintegerfalsefalseThe id of the section to which this section belongs. Only writable for Guide Enterprise customers
positionintegerfalsefalseThe position of this section in the section list. Used when sorting is set to ┬┤manual┬┤. By default the section is added to the end of the list
source_localestringtruefalseThe source (default) locale of the section
theme_templatestringfalsefalseThe theme template name used to display this section in Help Center.
updated_atstringtruefalseThe time at which the section was last updated
urlstringtruefalseThe API url of this section

Example

{  "category_id": 3465,  "description": "This section contains tricks for the airborne",  "id": 1635,  "locale": "en-us",  "name": "Avionics"}

List Sections

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

Lists all the sections in Help Center or in a specific category.

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

Allowed for

  • Anonymous users

The response will list only the sections that the requesting 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/sections.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
categoriesthe category
translationsthe section and category translations, if any

Unlike other sideloads, translations are embedded within the section because they're not shared between resources. Category translations are only sideloaded if categories are.

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}/sections.json \-v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/sections?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 "username:password"
	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/sections")		.newBuilder()		.addQueryParameter("sort_by", "")		.addQueryParameter("sort_order", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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/sections',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'sort_by': '',    'sort_order': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/help_center/en-us/sections?sort_by=&sort_order="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/sections")uri.query = URI.encode_www_form("sort_by": "", "sort_order": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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
{  "sections": [    {      "category_id": 888887,      "description": "This section contains articles on flight instruments",      "id": 35467,      "locale": "en-us",      "name": "Avionics"    },    {      "category_id": 887285,      "description": "This section contains weather resources for pilots",      "id": 36169,      "locale": "en-us",      "name": "Weather"    }  ]}

Show Section

  • GET /api/v2/help_center/{locale}/sections/{section_id}
  • GET /api/v2/help_center/sections/{section_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
categoriesthe category
translationsthe section and category translations, if any

Unlike other sideloads, translations are embedded within the section since they're not shared between resources. Category translations are only sideloaded if categories are.

Parameters

NameTypeInRequiredDescription
localestringPathtrueThe locale the item is displayed in
section_idintegerPathtrueThe unique ID of the section

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections/{section_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"	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 "username:password"
	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/sections/360004785313")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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/sections/360004785313',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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
{  "section": {    "description": "This section contains articles on flight instruments",    "id": 3457836,    "locale": "en-us",    "name": "Avionics",    "position": 2  }}

Create Section

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

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

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}/sections.json \  -d '{"section": {"position": 2, "locale": "en-us", "name": "Avionics", \    "description": "This section contains articles on flight instruments"}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
# You can also specify multiple translations for the new section:
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}/sections.json \  -d '{"section": {"position": 2, "translations":  \    [{"locale": "en-us", "title": "Avionics", \    "body": "This section contains articles on flight instruments"}, \    {"locale": "fr", "title": "Avionique", \    "body": "Cette section contient des articles sur les instruments de vol"}]}}' \  -v -u {email_address}:{password} -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/360002011513/sections"	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 "username:password"
	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/sections")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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/360002011513/sections',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/sections"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/categories/360002011513/sections")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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
{  "section": {    "description": "This section contains articles on flight instruments",    "id": 3457836,    "locale": "en-us",    "name": "Avionics",    "position": 2  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": {    "parent_section_id": [      "cannot be assigned non-null value on this Guide plan"    ]  }}

Update Section

  • PUT /api/v2/help_center/{locale}/sections/{section_id}
  • PUT /api/v2/help_center/sections/{section_id}

Update section. This endpoint updates section-level data, specifically:

  • name (in the source locale)
  • description (in the source locale)
  • position
  • sorting
  • category_id
  • parent_section_id
  • theme_template

To update non-source section translations, see Translations.

Allowed for

  • Help Center managers

Parameters

NameTypeInRequiredDescription
localestringPathtrueThe locale the item is displayed in
section_idintegerPathtrueThe unique ID of the section

Example body

{  "section": {    "position": 3  }}

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}.json \-d '{"section": {"position": 42}}' \-v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"	method := "PUT"	payload := strings.NewReader(`{  "section": {    "position": 3  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	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/sections/360004785313")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"section\": {    \"position\": 3  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "section": {    "position": 3  }});
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"
payload = json.loads("""{  "section": {    "position": 3  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.body = %q({  "section": {    "position": 3  }})request.basic_auth "username", "password"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
{  "section": {    "description": "This section contains articles on flight instruments",    "id": 3457836,    "locale": "en-us",    "name": "Avionics",    "position": 2  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": {    "parent_section_id": [      "would result in a cycle"    ]  }}

Update Section Source Locale

  • PUT /api/v2/help_center/{locale}/sections/{section_id}/source_locale
  • PUT /api/v2/help_center/sections/{section_id}/source_locale

This endpoint lets you set a section's source language to something other than the default language of your Help Center. For example, if the default language of your Help Center is English but your KB has a section only for Japanese customers, you can set the section's source locale to 'ja'.

Allowed for

  • Help Center managers

Parameters

NameTypeInRequiredDescription
localestringPathtrueThe locale the item is displayed in
section_idintegerPathtrueThe unique ID of the section

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/source_locale.json \-d '{"section_locale": "fr"}' -v -u {email_address}:{password} -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/sections/360004785313/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 "username:password"
	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/sections/360004785313/source_locale")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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/sections/360004785313/source_locale',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313/source_locale"headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313/source_locale")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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 Section

  • DELETE /api/v2/help_center/{locale}/sections/{section_id}
  • DELETE /api/v2/help_center/sections/{section_id}

WARNING: All articles in the section will also be deleted.

Allowed for

  • Help Center managers

Parameters

NameTypeInRequiredDescription
localestringPathtrueThe locale the item is displayed in
section_idintegerPathtrueThe unique ID of the section

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}.json \  -v -u {email_address}:{password} -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"	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 "username:password"
	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/sections/360004785313")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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/sections/360004785313',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/help_center/en-us/sections/360004785313")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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