Articles

JSON Format

Articles are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
author_id integer false false The id of the user who wrote the article (set to the user who made the request on create by default)
body string false false The body of the article
comments_disabled boolean false false True if comments are disabled; false otherwise
created_at string true false The time the article was created
draft boolean true false True if the translation for the current locale is a draft; false otherwise. false by default. Can be set when creating but not when updating. For updating, see Translations
edited_at string true false The time the article was last edited in its displayed locale
html_url string true false The url of the article in Help Center
id integer true false Automatically assigned when the article is created
label_names array false false An array of label names associated with this article. By default no label names are used. Only available on certain plans
locale string false true The locale that the article is being displayed in
outdated boolean true false Deprecated. Always false because the source translation is always the most up-to-date translation
outdated_locales array true false Locales in which the article was marked as outdated
permission_group_id integer false true The id of the permission group which defines who can edit and publish this article
position integer false false The position of this article in the article list. 0 by default
promoted boolean false false True if this article is promoted; false otherwise. false by default
section_id integer false false The id of the section to which this article belongs
source_locale string true false The source (default) locale of the article
title string false true The title of the article
updated_at string true false The time the article was last updated
url string true false The API url of the article
user_segment_id integer false true The id of the user segment which defines who can see this article. Set to null to make it accessible to everyone
vote_count integer true false The total number of upvotes and downvotes
vote_sum integer true false The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
Example
{
  "author_id": 3465,
  "comments_disabled": false,
  "id": 1635,
  "locale": "en",
  "permission_group_id": 13,
  "title": "The article",
  "user_segment_id": 12
}

List Articles

  • GET /api/v2/help_center{/locale}/articles
  • GET /api/v2/help_center/{locale}/categories/{category_id}/articles
  • GET /api/v2/help_center/{locale}/sections/{section_id}/articles
  • GET /api/v2/help_center/users/{user_id}/articles
  • GET /api/v2/help_center/incremental/articles?start_time={start_time}

These endpoints let you list all articles in Help Center, all articles in a given category or section, or all the articles authored by a specific agent. You can also list all articles with metadata that changed since a specified start time.

To list articles by content changes, not metadata changes, filter the articles by the updated_at timestamp of the articles' translations.

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

You can also use the Search API to list articles. See Search.

Allowed for
  • Agents
  • End users
  • Anonymous users

The response lists only the articles 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/articles.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
title order alphabetically by title
created_at order by creation time
updated_at order by update time

When sorting by title, the endpoint must specify a locale for the titles. Example:

/api/v2/help_center/en-us/articles.json?sort_by=title

The sort_order parameter can have one of the following values:

value description
asc ascending order
desc descending order

Note that if sorting parameters are not passed to the section-scoped articles endpoint (/api/v2/help_center/{locale}/sections/{section_id}/articles.json), articles will be returned in the order defined on the section itself. See Organizing knowledge base content in categories and sections for more information about defining sort orders on sections.

Options
Start Time

You can use the incremental article endpoint to list all the articles that were updated since a certain date and time. The endpoint takes a start_time parameter with a Unix epoch time. Example:

/api/v2/help_center/incremental/articles.json?start_time=1404345231
Label Names

You can specify that only articles with specific labels should be returned by adding a label_names parameter. The parameter takes a comma-separated list of up to 10 label names. Example:

/api/v2/help_center/en-us/articles.json?label_names=photos,camera

Only articles that have all the labels are returned. For example, label_names=photos,camera returns all articles that have both 'photo' AND 'camera' labels. If you want the articles that have either 'photo' OR 'camera' labels, you can use the Search Article endpoint with the label_names parameter (Professional and Enterprise).

Matching is case-sensitive. For example, 'camera' matches 'camera' but not 'Camera'.

Sideloads

The following sideloads are supported:

Name Will sideload
users the author
sections the section
categories the category
translations the article, section and category translations, if any

Unlike other sideloads, translations are embedded within the article because they're not shared between resources. Section and category translations are only sideloaded if present.

Parameters
Name Type In Required Description
label_names string Query false Only articles that have all the labels are returned.
sort_by string Query false Sorts the articles by one of the accepted values. Allowed values are "position", "title", "created_at" or "updated_at".
sort_order string Query false Selects the order of the results. Allowed values are "asc" or "desc".
start_time integer Query false You can use the incremental article endpoint to list all the articles that were updated since a certain date and time.
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "articles": [
    {
      "author_id": 888887,
      "draft": true,
      "id": 35467,
      "locale": "en",
      "permission_group_id": 123,
      "title": "Article title",
      "user_segment_id": 12
    }
  ]
}

Show Article

  • GET /api/v2/help_center{/locale}/articles/{article_id}

Shows the properties of an article.

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

Allowed for
  • Agents
  • End users
Sideloads

The following sideloads are supported:

Name Will sideload
users the author
sections the section
categories the category
translations the article, section and category translations, if any

Unlike other sideloads, translations are embedded within the article because they're not shared between resources. Section and category translations are only sideloaded if present.

Parameters
Name Type In Required Description
article_id integer Path true The unique ID of this Article
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles/{article_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "article": {
    "author_id": 3465,
    "comments_disabled": true,
    "id": 37486578,
    "locale": "en_us",
    "permission_group_id": 123,
    "position": 42,
    "promoted": false,
    "title": "Article title",
    "user_segment_id": 12
  }
}

Update Article

  • PUT /api/v2/help_center{/locale}/articles/{article_id}
  • PUT /api/v2/help_center/articles/{article_id}.json

These endpoints update article-level metadata such as its promotion status or sorting position. The endpoints do not update translation properties such as the article's title, body, locale, or draft. See Translations.

Allowed for
  • Agents
Parameters
Name Type In Required Description
article_id integer Path true The unique ID of this Article
locale string Path false The locale that the category is displayed in
Using curl

For clarity, the example places the JSON payload in a separate file and the cURL statement imports the file.

article.json

{
  "article": {
    "promoted": false,
    "position": 42,
    "comments_disabled": true,
    "label_names": ["photo", "tripod"]
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}.json \
  -d @article.json \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "article": {
    "author_id": 3465,
    "comments_disabled": true,
    "id": 37486578,
    "locale": "en_us",
    "permission_group_id": 123,
    "position": 42,
    "promoted": false,
    "title": "Article title",
    "user_segment_id": 12
  }
}

Archive Article

  • DELETE /api/v2/help_center{/locale}/articles/{article_id}

Archives the article. You can restore the article using the Help Center user interface. See Viewing and restoring archived articles.

Allowed for
  • Agents
Parameters
Name Type In Required Description
article_id integer Path true The unique ID of this Article
locale string Path false The locale that the category is displayed in
Using
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content

Associate Attachments in Bulk to Article

  • POST /api/v2/help_center{/locale}/articles/{article_id}/bulk_attachments

You can associate attachments in bulk to only one article at a time, with a maximum of 20 attachments per request.

To create the attachments, see Create Unassociated Attachment.

Allowed for
  • Agents
Parameters
Name Type In Required Description
article_id integer Path true The unique ID of this Article
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/bulk_attachments.json \
  -d '{"attachment_ids": [10002, ...]}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
Example Response
Status 200 OK

Update Article Source Locale

  • PUT /api/v2/help_center{/locale}/articles/{article_id}/source_locale

The endpoint updates article source_locale property

Allowed for
  • Agents
Parameters
Name Type In Required Description
article_id integer Path true The unique ID of this Article
locale string Path false The locale that the category is displayed in
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/source_locale.json \
  -d '{"article_locale": "fr"}' -v -u {email_address}:{password} -X PUT \
  -H "Content-Type: application/json"
Example Response
Status 200 OK

Create Article

  • POST /api/v2/help_center{/locale}/sections/{section_id}/articles

Creates an article in the specified section. You must specify an article title, locale, user_segment_id, and permission_group_id. The locale can be omitted if it's specified in the URL. Optionally, you can specify multiple translations for the article. The specified locales must be enabled for the current Help Center.

The current user is automatically subscribed to the article and will receive notifications when it changes.

The current user must be a member of the specified permission_group_id. To create a published article (draft=false or missing), the current user must have publishing rights as part of the permission_group_id that is provided. Otherwise, the article must be created using draft=true.

Allowed for
  • Agents

Supplying a notify_subscribers property with a value of false will prevent subscribers to the article from receiving an article creation email notification. This can be helpful when creating many articles at a time. Specify the property in the root of the JSON object, not in the "article" object.

Parameters
Name Type In Required Description
locale string Path false The locale that the category is displayed in
section_id integer Path true The unique ID of this Section
Example Body
{
  "article": {
    "body": "Use a tripod",
    "locale": "en-us",
    "permission_group_id": 56,
    "title": "Taking photos in low light",
    "user_segment_id": 123
  },
  "notify_subscribers": false
}
Using curl

For clarity, the example places the JSON payload in a separate file and the cURL statement imports the file.

article.json

{
  "article": {
    "title": "Taking photos in low light",
    "body": "Use a tripod",
    "locale": "en-us",
    "user_segment_id": 123,
    "permission_group_id": 56
  },
  "notify_subscribers": false
}

With translations

{
  "article": {
    "translations": [
      {
        "locale": "en-us",
        "title": "Taking photos in low light",
        "body": "Use a tripod"
      },
      {
        "locale": "fr",
        "title": "Comment prendre des photos en basse lumiere",
        "body": "Utilisez un trepied"
      }
    ],
    "user_segment_id": 123,
    "permission_group_id": 56
  },
  "notify_subscribers": false
}

curl snippet

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/articles.json \
  -d @article.json \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "article": {
    "author_id": 3465,
    "comments_disabled": true,
    "id": 37486578,
    "locale": "en_us",
    "permission_group_id": 123,
    "position": 42,
    "promoted": false,
    "title": "Article title",
    "user_segment_id": 12
  }
}