Articles are represented as JSON objects with the following properties:

{
  "author_id": 3465,
  "comments_disabled": false,
  "id": 1635,
  "locale": "en",
  "permission_group_id": 13,
  "title": "The article",
  "user_segment_id": 12
}

• 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.

• 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.

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:

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:

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.

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

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'.

The following sideloads are supported:

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.

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles.json \
  -v -u {email_address}:{password}

Status 200 OK

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

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

Shows the properties of an article.

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

• Agents
• End users

The following sideloads are supported:

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.

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles/{article_id}.json \
-v -u {email_address}:{password}

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

• 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.

• Agents

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}

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

• 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.

• Agents

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}.json \
  -v -u {email_address}:{password} -X DELETE

Status 204 No Content

• 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.

• Agents

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"

Status 200 OK

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

The endpoint updates article source_locale property

• Agents

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"

Status 200 OK

• 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.

• 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.

{
  "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
}

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}

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