unified_search_api_draft.md

gistfile1.txt

## Search



You can use the API to search for knowledge base articles, community posts, or well as external records.

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.


### JSON Format

Search are represented as JSON objects with the following properties:

| Name | Type | Read-only | Mandatory | Description |
| ---- | ---- | --------- | ----------| ---------|
| results | array | false | true | An array with the base articles, community posts or external records |



### Unified Search

* `GET /api/v2/help_center/search`

Returns a default number of 25 search results per page, which can include articles, community posts and external records up to a maximum of 1000 results. 
See [Pagination](https://developer.zendesk.com/rest_api/docs/support/introduction#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 search result objects] returned by the search endpoint will always include the following two properties:

| Name        | Type   | Read-only | Mandatory | Comment
|-------------|--------|-----------|-----------|-------
| result_type | string | yes       | no        | This will either be "article", "post" or "external_record".
| snippet     | string | yes       | no        | The portion of the search result 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>`..."

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

- query
- placements
- labels

#### Allowed for

* ~Anonymous users~
* Authenticated users


#### 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/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 or community post 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 or post.


#### 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 your content in another language.

`GET /api/v2/help_center/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](https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#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 Source

##### Filtering by Brand
Use the `source[brand]` parameter to scope the result of your search to a specific brand or brands.

`GET /api/v2/help_center/search.json?query={search_string}&source[brand]={brand_id}`

If you want to scope the result of your search with multiple brands, use the `source[brand_id]` parameter as above and separate each value with a comma.

`GET /api/v2/help_center/search.json?query={search_string}&source[brand]={brand_id},{another_brand_id}`


##### Filtering by External Source
Use the `source[external_source]` parameter to scope the result of your search to a specific external source or external sources.

`GET /api/v2/help_center/search.json?query={search_string}&source[external_source]={external_source_id}`

If you want to scope the result of your search with multiple brands, use the `source[external_source]` parameter as above and separate each value with a comma.

`GET /api/v2/help_center/search.json?query={search_string}&source[external_source]={external_source_id},{external_source_id}`
  
#### Parameters
| Name | Type | In | Required | Description |
| ---- | ---- | -- | ---------| ---------|
| content_type | string | Query | false | Search across specific content types, specifying whether to search for "ARTICLE", "POST", or "EXTERNAL_RECORD"  |
| created_after | string | Query | false | Limit the search to articles created after a given date (format YYYY-MM-DD).  |
| created_at | string | Query | false | Limit the search to articles created on a given date (format YYYY-MM-DD).  |
| created_before | string | Query | false | Limit the search to articles created before a given date (format YYYY-MM-DD).  |
| labels | string | Query | false | A comma-separated list of label names. See [Filtering by Labels](#filtering-by-labels) |
| locale | string | Query | false | Search for articles in the specified locale. See [Filtering by Locale](#filtering-by-locale) |
| placements | integer | Query | false | Search for articles in specific sections or categories, or community posts by topic. See [Filtering by Category](#filtering-by-category), [Filtering by Section](#filtering-by-section), [Filtering by Topic](#filtering-by-topic) |
| query | string | Query | false | The search text to be matched or a search string. Examples: "carrot potato", "'carrot potato'".  |
| sort_by | string | Query | false | One of created_at or updated_at. Defaults to sorting by relevance |
| sort_order | string | Query | false | One of asc or desc. Defaults to desc |
| source | integer | Query | false | Search across specific brands or external sources. See [Filtering by Brand](#filtering-by-brand) and [Filtering by Filtering by External Source](#filtering-by-external-source) |
| updated_after | string | Query | false | Limit the search to articles updated after a given date (format YYYY-MM-DD).  |
| updated_at | string | Query | false | Limit the search to articles updated on a given date (format YYYY-MM-DD).  |
| updated_before | string | Query | false | Limit the search to articles updated before a given date (format YYYY-MM-DD).  |


### Scoping search to Articles

* `GET /api/v2/help_center/search?query={search_string}&content_types=ARTICLE`

Returns a default number of 25 articles per page, up to a maximum of 1000 results. 
The results are sorted by relevance by default. You can also sort the results by `created_at` or `updated_at`.

#### Article search filtering

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

`GET /api/v2/help_center/search.json?labels=photos,camera`

Note: Filtering by labels will *only* return articles in the results, as community posts and external records cannot have labels.

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 Category
If you want to scope the result of your search within a given category, use the `placements[category]` parameter.

`GET /api/v2/help_center/search.json?query={search_string}&placements[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/search.json?query={search_string}&placements[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 `placements[section]` parameter.

`GET /api/v2/help_center/search.json?query={search_string}&placements[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/search.json?query={search_string}&section={section_id},{another_section_id}`

  
#### Article Specific Parameters
| Name | Type | In | Required | Description |
| ---- | ---- | -- | ---------| ---------|
| labels | string | Query | false | A comma-separated list of label names. See [Filtering by Labels](#filtering-by-labels) |
| placements[category] | integer | Query | false | Limit the search to this category id. See [Filtering by Category](#filtering-by-category) |
| placements[section] | integer | Query | false | Limit the search to this section id. See [Filtering by Section](#filtering-by-section) |
| source[brand_id] | integer | Query | false | Search for articles in the specified brand.  |


### Scoping search to Community Posts

* `GET /api/v2/help_center/search?query={query}&content_types=POST`

Returns a maximum of 25 posts per page, up to a maximum of 1000 results. See [Pagination](https://developer.zendesk.com/rest_api/docs/support/introduction#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`.


#### Filtering by Topic

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

`GET /api/v2/help_center/search.json?query={search_string}&placements[topic]={topic_id}`

  
#### Community Post Specific Parameters
| Name | Type | In | Required | Description |
| ---- | ---- | -- | ---------| ---------|
| placements[topic] | integer | Query | false | Limit the search to this topic id. See [Filtering by Topic](#filtering-by-topic) |
| source[brand_id] | integer | Query | false | Search for community posts in the specified brand.  |


### Scoping search to External Content

* `GET /api/v2/help_center/search?query={query}&content_types=EXTERNAL_RECORD`

Returns a maximum of 25 external records per page, up to a maximum of 1000 results. See [Pagination](https://developer.zendesk.com/rest_api/docs/support/introduction#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`.


#### Filtering by External Source

If you want to scope the result of your search within a given source, use the `source[external_source]` parameter.

`GET /api/v2/help_center/search.json?query={search_string}&source[external_source]={external_source_id}`

  
#### Community Post Specific Parameters
| Name | Type | In | Required | Description |
| ---- | ---- | -- | ---------| ---------|
| source[external_source] | integer | Query | false | Search for external records that have come from the specified source.  |