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 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 at which the article was created
updated_at timestamp yes no The time at which the article was last updated

Example

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

List Articles

  1. GET /api/v2/help_center/articles.json
  2. GET /api/v2/help_center/{locale}/articles.json
  3. GET /api/v2/help_center/categories/{id}/articles.json
  4. GET /api/v2/help_center/sections/{id}/articles.json
  5. GET /api/v2/help_center/users/{id}/articles.json
  6. 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 have been updated since a specified start time.

Allowed for

  • Agents
  • End-users

The response will list only the articles that the requesting agent or end-user can view in Help Center.

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_name 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)

Show Article

  1. GET /api/v2/help_center/articles/{id}.json
  2. 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,
    ...
  }
}

Update Article

  1. PUT /api/v2/help_center/articles/{id}.json
  2. 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,
    ...
  }
}

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: 200 OK

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"

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,
    ...
  }
}

Search Articles

GET /api/v2/help_center/articles/search.json?query={search_string}

Allowed for

  • Anonymous users

Available Parameters

Name Type Required Comments
query string yes The search text to be matched or a search string. Examples: "carrot potato", "'carrot potato'".
sort_by string no Possible values are 'updated_at'
category integer no Limit the search to this category id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/search.json?query={search_string} \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "results": [
    {
      "id":                1635,
      "author_id":         3465,
      "published":         true,
      "comments_disabled": false,
      ...
    },
    {
      "id":                1771,
      "author_id":         3601,
      "published":         true,
      "comments_disabled": true,
      ...
    },
    ...
  ]
}

comments powered by Disqus