Articles

JSON Format

Articles have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the article is created
url string yes no The API url of the article
html_url string yes no The url of the article in Help Center
title string no yes The title of the article
body string no no The body of the article
locale string no yes The locale that the article is being displayed in
source_locale string yes no The source (default) locale of the article
author_id integer no no The id of the user who wrote the article (set to the user who made the request on create by default)
comments_disabled boolean no no True if comments are disabled; false otherwise
outdated boolean yes no Whether the source (default) translation of the article is out of date
label_names string no no An array of label names associated with this article. By default no label names are used. Only available on certain plans
draft boolean no no True if the translation for the current locale is a draft; false otherwise. false by default
promoted boolean no no True if this article is promoted; false otherwise. false by default
position integer no no The position of this article in the article list. 0 by default
vote_sum integer yes no The total sum of votes on this article
vote_count integer yes no The number of votes cast on this article
section_id integer no no The id of the section to which this article belongs
created_at timestamp yes no The time the article was created
updated_at timestamp yes no The time the article was last updated
Example
{
  "id":                1635,
  "author_id":         3465,
  "comments_disabled": false,
  ...
}

List Articles

  • GET /api/v2/help_center/articles.json
  • GET /api/v2/help_center/{locale}/articles.json
  • GET /api/v2/help_center/categories/{id}/articles.json
  • GET /api/v2/help_center/sections/{id}/articles.json
  • GET /api/v2/help_center/users/{id}/articles.json
  • GET /api/v2/help_center/incremental/articles.json?start_time={start_time}

These endpoints let you list all articles, all articles in a locale, all articles in a given category or section, or all the articles provided by a specific agent. You can also list all articles that were updated since a specified start time.

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

Allowed for
  • Agents
  • End-users

The response lists only the articles that the requesting agent or end-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:

GET /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
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.

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

{
  "articles": [
    {
      "id":        35467,
      "author_id": 888887,
      "draft":     true,
      ...
    },
    ...
  ]
}
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:

GET /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 should be a comma-separated list of label names:

  • label_names (GET /api/v2/help_center/articles.json?label_names=photos,camera)

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

Show Article

  • GET /api/v2/help_center/articles/{id}.json
  • GET /api/v2/help_center/{locale}/articles/{id}.json

Shows the properties of an article.

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.

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

{
  "article": {
    "id":                1635,
    "author_id":         3465,
    "draft":             true,
    "comments_disabled": false,
    ...
  }
}

Create Article

  • POST /api/v2/help_center/sections/{id}/articles.json
  • POST /api/v2/help_center/{locale}/sections/{id}/articles.json

Creates an article in the specified section. You must specify an article title and locale. 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.

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}/articles.json \
  -d '{"article": {"promoted": false, "position": 2, \
    "comments_disabled": true, "label_names": ["photo", "tripod"], "locale": "en-us", \
    "title": "How to take pictures in low light", "body": "Use a tripod" }}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

You can also specify multiple translations for the new article:

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}/articles.json \
  -d '{"article": {"promoted": false, "position": 2, \
    "comments_disabled": true, "label_names": ["photo", "tripod"], "translations": [ \
    {"locale": "en-us", "title": "How to take pictures in low light", "body": "Use a tripod"}, \
    {"locale": "fr", "title": "Comment prendre des photos en basse lumiere", "body": "Utilisez un trepied"}]}}' \
  -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/articles/{id}.json

{
  "article": {
    "id":                37486578,
    "author_id":         3465,
    "promoted":          false,
    "position":          42,
    "comments_disabled": true,
    "section_id":        98838,
    ...
  }
}

Update Article

  • PUT /api/v2/help_center/articles/{id}.json
  • PUT /api/v2/help_center/{locale}/articles/{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 or body. See Translations.

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{id}.json \
  -d '{"article": {"promoted": false, "position": 42, \
       "comments_disabled": true, "label_names": ["photo", "tripod"]}}' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
Status: 200 OK

{
  "article": {
    "id":                37486578,
    "author_id":         3465,
    "promoted":          false,
    "position":          42,
    "comments_disabled": true,
    ...
  }
}

Associate Attachments in Bulk to Article

POST /api/v2/help_center/articles/{id}/bulk_attachments.json

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{id}/bulk_attachments.json \
  -d '{"attachment_ids": [10002, ...]}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Update Article Source Locale

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

The endpoint updates article source_locale property

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{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

Delete Article

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

Allowed for
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 OK