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_locales | array | yes | no | Locales in which the article was marked as outdated |
outdated | boolean | yes | no | Deprecated. Always false because the source translation is always the most up-to-date translation |
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 | yes | no | 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 |
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 sum of upvotes (+1) and downvotes (-1), which may be positive or negative |
vote_count | integer | yes | no | The total number of upvotes and downvotes |
section_id | integer | no | no | The id of the section to which this article belongs |
user_segment_id | integer | no | yes | The id of the user segment which defines who can see this article. Set to null to make it accessible to everyone |
permission_group_id | integer | no | yes | The id of the permission group which defines who can edit and publish this article |
created_at | timestamp | yes | no | The time the article was created |
edited_at | timestamp | yes | The time the article was last edited in its displayed locale | |
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/{locale}/articles.json
GET /api/v2/help_center/{locale}/categories/{id}/articles.json
GET /api/v2/help_center/{locale}/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 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/{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.
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/{locale}/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:
/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'.
Show Article
GET /api/v2/help_center/{locale}/articles/{id}.json
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.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/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, 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.
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
}
cURL statement
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}/articles.json \
-d @article.json \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
You can also specify multiple translations for the new article. The JSON payload looks as follows:
{
"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
}
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, body, locale, or draft. See Translations.
Allowed for
- Agents
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 statement
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{id}.json \
-d @article.json \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
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
Archive Article
DELETE /api/v2/help_center/articles/{id}.json
Archives the article. You can restore the article using the Help Center user interface. See Viewing and restoring archived articles.
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 No Content