Search

You can use the API to search for knowledge base articles or community posts.

You can call this API from a JavaScript client in a domain other than your Help Center. The API implements Cross-Origin Resource Sharing (CORS). CORS lets a JavaScript client access resources in other domains.

Search Articles

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

Returns a default number of 25 articles per page, up to a maximum of 1000 results. See Pagination in the Core API docs. The per_page parameter, if provided, must be an integer between 1 and 100. The page parameter, if provided, must be an integer greater than 0. The results are sorted by relevance by default. You can also sort the results by created_at or updated_at.

The article objects returned by the search endpoint contain two additional properties:

Name Type Read-only Mandatory Comment
result_type string yes no For articles, always the string "article"
snippet string yes no The portion of an article that is relevant to the search query, with matching words or phrases delimited by <em></em> tags. Example: a query for "carrot potato" might return the snippet "...don't confuse <em>carrots</em> with <em>potatoes</em>..."
Allowed for
  • Anonymous users
Available Parameters
Name Type Required Comments
query string no The search text to be matched or a search string. Examples: "carrot potato", "'carrot potato'".
category integer no Limit the search to this category id. See Filtering by Category
section integer no Limit the search to this section id. See Filtering by Section
label_names string no A comma-separated list of label names. See Filtering by Labels
locale string no Search for articles in the specified locale. See Filtering by Locale
multibrand boolean no Enable search across all brands if true. Defaults to false if omitted. See Filtering by Brand
brand_id integer no Search for articles in the specified brand. See Filtering by Brand
created_before date no Limit the search to articles created before a given date (format YYYY-MM-DD)
created_after date no Limit the search to articles created after a given date (format YYYY-MM-DD)
created_at date no Limit the search to articles created on a given date (format YYYY-MM-DD)
updated_before date no Limit the search to articles updated before a given date (format YYYY-MM-DD)
updated_after date no Limit the search to articles updated after a given date (format YYYY-MM-DD)
updated_at date no Limit the search to articles updated on a given date (format YYYY-MM-DD)
sort_by string no One of created_at or updated_at. Defaults to sorting by relevance
sort_order string no One of asc or desc. Defaults to desc

You must specify at least one of the following parameters in your request:

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

If using the command line, use commas to separate multiple search terms. Example:

search.json?query=print,orders

Example Response
Status: 200 OK

{
  "results": [
    {
      "id":        35467,
      "author_id": 888887,
      "draft":     false,
      "title":     "Printing orders",
      ...
    },
    ...
  ]
}
Filtering by Date

You can filter the search results by the creation or update date with the following parameters:

  • created_before
  • created_after
  • created_at
  • updated_before
  • updated_after
  • updated_at

GET /api/v2/help_center/articles/search.json?query={search_string}&updated_after=2014-01-01&updated_before=2014-02-01

When filtering by updated_*, the results might not always match the updated_at timestamps for the documents returned. The reason is that not all updates are propagated to the search index. Only updates that are meaningful for search, such as content changes, are re-indexed. As a result, it's possible for an article to have an updated_at timestamp of "2019-10-31" but be returned in a search with the filter updated_before=2019-08-01 if no meaningful content changes have been made to the article.

Filtering by Labels

If you want to search for articles with specific labels, use the label_names parameter and pass a comma-separated list of label names to filter the results:

GET /api/v2/help_center/articles/search.json?label_names=photos,camera

An article must have at least one of the labels to match. Also, matching is not case-sensitive. For example, 'camera' matches both 'Camera' and 'camera'.

This feature is only available on Professional and Enterprise.

Filtering by Locale

By default, searches are carried out in the default language specified in the Help Center settings. Use the locale parameter to search for articles in another language.

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

If you specify an invalid locale or a locale that's not enabled for Help Center, the default locale for the account is used for the search. You can check for valid locales with the API. See List all enabled locales and default locale.

If you use locale=*, search is carried out across all valid locales and returns all article translations in all languages, that match the search criteria.

Filtering by Category

If you want to scope the result of your search within a given category, use the category parameter.

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

If you want to scope the result of your search with multiple categories, use the category parameter as above and separate each value with a comma.

GET /api/v2/help_center/articles/search.json?query={search_string}&category={category id},{another category id}

Filtering by Section

If you want to scope the result of your search within a given section, use the section parameter.

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

If you want to scope the result of your search with multiple sections, use section parameter as above and separate each value with a comma.

GET /api/v2/help_center/articles/search.json?query={search_string}&section={section id},{another section id}

Filtering by Brand

Use the multibrand parameter to search across all brands, or brand_id to scope the result of your search to a specific brand.

GET /api/v2/help_center/articles/search.json?query={search_string}&brand_id={brand id}

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

If you use multibrand=true in your request and no brand_id, search will return results from all brands that match the query criteria. If you use brand_id in your request, the search results will be scoped to the specified brand, regardless of the use of the multibrand parameter.

Search Posts

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

Returns a maximum of 25 posts per page, up to a maximum of 1000 results. See Pagination in the Core API docs. The results are sorted by relevance by default. You can also sort the results by created_at or updated_at.

Allowed for
  • End 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'"
topic integer no Limit the search to a topic id. See Filtering by Topic
created_before date no Limit the search to posts created before a given date (format YYYY-MM-DD)
created_after date no Limit the search to posts created after a given date (format YYYY-MM-DD)
created_at date no Limit the search to posts created on a given date (format YYYY-MM-DD)
updated_before date no Limit the search to posts updated before a given date (format YYYY-MM-DD)
updated_after date no Limit the search to posts updated after a given date (format YYYY-MM-DD)
updated_at date no Limit the search to posts updated on a given date (format YYYY-MM-DD)
sort_by string no One of created_at or updated_at. Defaults to sorting by relevance
sort_order string no One of asc or desc. Defaults to desc
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/help_center/community_posts/search.json?query={search_string}" \
  -v -u {email_address}:{password}

If using the command line, use commas to separate multiple search terms. Example:

search.json?query=print,orders

Example Response
Status: 200 OK

{
  "results": [
    {
      "id":        4212256,
      "author_id": 4333787,
      "title":     "How do I make a return?",
      ...
    },
    ...
  ]
}
Filtering by Date

You can filter the search results by the creation or update date with the following parameters:

  • created_before
  • created_after
  • created_at
  • updated_before
  • updated_after
  • updated_at

GET /api/v2/community/posts/search.json?query={search_string}&updated_after=2014-01-01&updated_before=2014-02-01

Filtering by Topic

If you want to scope the result of your search within a given topic, use the topic parameter.

GET /api/v2/community/posts/search.json?query={search_string}&topic={topic id}