Help Center API

Sections

JSON Format

Sections have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating subscriptions
name string no yes The name of the section
description string no no The description of the section
locale string no yes The locale in which the section is displayed
source_locale string yes no The source (default) locale of the section
url string yes no The API url of this section
html_url string yes no The url of this section in HC
category_id integer no no The id of the category to which this section belongs
outdated boolean yes no Whether the section is out of date
parent_section_id integer no no The id of the section to which this section belongs. Only writable for Guide Enterprise customers
position integer no no The position of this section in the section list. By default the section is added to the end of the list
manageable_by string no no Deprecated. The set of users who can manage this section
user_segment_id integer no no Deprecated. The id of the user segment to which this section belongs.
created_at timestamp yes no The time at which the section was created
updated_at timestamp yes no The time at which the section was last updated

The manageable_by attribute takes one of the following values:

Value Users
staff agents and managers
managers only Help Center managers

Note that manageable_by is only displayed to users who can manage the section.

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

List Sections
  • GET /api/v2/help_center/{locale}/sections.json
  • GET /api/v2/help_center/{locale}/categories/{id}/sections.json

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
  • Agents
  • End users
  • Anonymous users

The response will list only the sections that the requesting 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/sections.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
categories the category
translations the 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.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "sections": [
    {
      "id":          35467,
      "category_id": 888887,
      "name":        "Avionics",
      "description": "This section contains articles on flight instruments",
      "locale":      "en-us",
      ...
    },
    {
      "id":          36169,
      "category_id": 887285,
      "name":        "Weather",
      "description": "This section contains weather resources for pilots",
      "locale":      "en-us",
      ...
    },
    ...
  ]
}

Show Section
  • GET /api/v2/help_center/{locale}/sections/{id}.json

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

Allowed for
  • Agents
  • End users
  • Anonymous users
Sideloads

The following sideloads are supported:

Name Will sideload
categories the category
translations the 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.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "section": {
    "id":          35467,
    "category_id": 888887,
    "name":        "Avionics",
    "description": "This section contains contains articles on flight instruments",
    "locale":      "en-us",
    ...
  }
}

Create Section
  • POST /api/v2/help_center/categories/{id}/sections.json
  • POST /api/v2/help_center/{locale}/categories/{id}/sections.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/categories/{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/{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"
Example Response
 
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}.json

{
  "section": {
    "id":          3457836,
    "name":        "Avionics",
    "description": "This section contains articles on flight instruments",
    "locale":      "en-us",
    "position":    2,
    ...
  }
}
Example Error Response
 
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/sections/{id}.json
  • PUT /api/v2/help_center/{locale}/sections/{id}.json

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

Allowed for
  • Help Center managers
Using curl
 
 curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}.json \
   -d '{"section": {"position": 42}}' \
   -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
 
Status: 200 OK

{
  "section": {
    "id":              37486578,
    "position":        42,
    ...
  }
}
Example Error Response
 
Status: 400 Bad Request

{
  "errors": {
    "parent_section_id": [
      "would result in a cycle"
    ]
  }
}

Update Section Source Locale

PUT /api/v2/help_center/sections/{id}/source_locale.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}/source_locale.json \
  -d '{"section_locale": "fr"}' -v -u {email_address}:{password} -X PUT \
  -H "Content-Type: application/json"
Example Response
 
Status: 200 OK

Delete Section

DELETE /api/v2/help_center/sections/{id}.json

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

Allowed for
  • Help Center managers
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status: 204 No Content